> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/atlas/llms.txt)

# Matrix API

The **[Mapbox Matrix API](https://docs.mapbox.com/api/navigation/matrix/)** is a feature of Atlas Navigation that returns travel times between many points, useful for grabbing the duration or distance of the fastest route for each element in the matrix, allowing you to efficiently check the reachability of coordinates from each other, filter points by travel time, or run your own algorithms for solving optimization problems.

For example, given three locations A, B, and C, the Matrix API will return a matrix of all travel times in seconds between the locations:

|  | A | B | C |
| --- | --- | --- | --- |
| A | A → A | A → B | A → C |
| B | B → A | B → B | B → C |
| C | C → A | C → B | C → C |

The Matrix API will always return the duration or the distance on the fastest route for each element in the matrix, where an element is an origin-destination pair in the matrix. The Matrix API returns durations in seconds and distances in meters. It does not return route geometries.

Durations or distances between points may not be symmetric, since the routes may differ by direction due to one-way streets or turn restrictions. For example, A to B may have a different duration than B to A.

The Matrix API allows you to efficiently check the reachability of coordinates from each other, filter points by travel time, or run your own algorithms for solving optimization problems.

## Setup

To use the Matrix API you need to enable the [Navigation](https://docs.mapbox.com/atlas/guides/navigation).

You can test the Matrix API with development version of the navigation data, but for production use you will likely need the full production data.

## Resource usage

Matrix API resource usage depends on the number of points, distance between them and the density of the roads network in the area.

![Atlas Matrix API Performance](https://docs.mapbox.com/assets/ideal-img/atlas-matrix-performance.280eb09.480.png)

Atlas running on a machine with an Intel `i7-11800H` (8 cores, 16 threads) with 30 gigabytes of memory allocated to the `valhalla-svc` container was able to achieve about 30 requests per second for a 10×10 matrix with 20 unique points located in a circle with a 10 kilometer radius.

A good sign that you need more resources is `500` errors under load and log lines containing `TIMEOUT ERROR` and `ESOCKETTIMEDOUT` in the `api-valhalla` container logs.

## API reference

### Retrieve a matrix

get

http://atlas.local/directions-matrix/v1/{profile}/{coordinates}?access_token={access_token}

Returns a duration matrix, a distance matrix, or both, showing travel times and distances between coordinates.

In the default case, this endpoint returns a symmetric matrix that uses all the input coordinates as sources and destinations (N×N). Using the optional `sources` and `destination` parameters, you can also generate an asymmetric matrix that uses only some coordinates as sources or destinations: one to many (1×N), many to one (N×1), several to several (M×N), and one to one (1×1).

| Required parameters | Type | Description |
| --- | --- | --- |
| `profile` | `string` | A Mapbox Directions [routing profile](https://docs.mapbox.com/api/navigation/directions/#routing-profiles) ID.
| Profile ID | Description |
| --- | --- |
| `mapbox/driving` | Car travel times, distances, or both. |
| `mapbox/walking` | Pedestrian and hiking travel times, distances, or both |
| `mapbox/cycling` | Bicycle travel times, distances, or both |
| `mapbox/driving-traffic` | Same as `mapbox/driving` because Atlas does not have traffic data |

 |
| `coordinates` | `number` | A semicolon-separated list of `{longitude},{latitude}` coordinates. There must be at least two coordinates. |
| `access_token` | `string` | An atlas access token. |

You can further refine the results from this endpoint with the following optional parameters:

| Optional parameters | Type | Description |
| --- | --- | --- |
| `annotations` | `string` | Used to specify the resulting matrices. Possible values are: `duration` (default), `distance`, or both values separated by a comma. |
| `approaches` | `string` | A semicolon-separated list indicating the side of the road from which to approach waypoints in a requested route. Accepts `unrestricted` (default, route can arrive at the waypoint from either side of the road) or `curb` (route will arrive at the waypoint on the `driving_side` of the region). If provided, the number of approaches must be the same as the number of waypoints. But, you can skip a coordinate and show its position in the list with the `;` separator. |
| `destinations` | `integer` or `string` | Use the coordinates at a given index as destinations. Possible values are: a semicolon-separated list of 0-based indices, or `all` (default). The option `all` allows using all coordinates as destinations. |
| `sources` | `integer` or `string` | Use the coordinates at a given index as sources. Possible values are: a semicolon-separated list of 0-based indices, or `all` (default). The option `all` allows using all coordinates as sources. |

#### Example request: Retrieve a matrix

```bash
# Request a symmetric 3x3 matrix for cars with a curbside approach for each destination

$ curl "http://atlas.local/directions-matrix/v1/mapbox/driving/-77.044966,38.9013257;-77.0153635,38.8947153;-77.0224982,38.9111173?approaches=curb;curb;curb&access_token=YOUR_ATLAS_ACCESS_TOKEN"

# Request an asymmetric 2x3 matrix for bicycles

$ curl "http://atlas.local/directions-matrix/v1/mapbox/cycling/-77.044966,38.9013257;-77.0153635,38.8947153;-77.0224982,38.9111173?sources=0;2&destinations=all&access_token=YOUR_ATLAS_ACCESS_TOKEN"

# Request a 1x3 matrix for walking that includes both duration and distance

$ curl "http://atlas.local/directions-matrix/v1/mapbox/walking/-77.044966,38.9013257;-77.0153635,38.8947153;-77.0224982,38.9111173?sources=1&annotations=distance,duration&access_token=YOUR_ATLAS_ACCESS_TOKEN"
```

#### Response: Retrieve a matrix

The response to a Matrix API request is a JSON object that contains the following properties:

| Property | Type | Description |
| --- | --- | --- |
| `code` | `string` | A string indicating the state of the response. This is a separate code than the HTTP status code. On normal valid responses, the value will be `Ok`. See the errors section below for more information. |
| `durations` | `array` | Durations as an array of arrays that represent the matrix in row-major order. `durations[i][j]` gives the travel time from the ith source to the jth destination. All values are in seconds. The duration between the same coordinate is always `0`. Finding no duration, the result will be `null`. |
| `distances` | `array` | Distances as an array of arrays that represent the matrix in row-major order. `distances[i][j]` gives the travel distance from the ith source to the jth destination. All values are in meters. The distance between the same coordinate is always `0`. Finding no distance, the result will be `null`. |
| `sources` | `array` | An `array` of [`waypoint` objects](https://docs.mapbox.com/api/navigation/directions/#waypoint-object). Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates, or in the order specified in the `sources` query parameter. |
| `destinations` | `array` | An `array` of [`waypoint` objects](https://docs.mapbox.com/api/navigation/directions/#waypoint-object). Each waypoint is an input coordinate snapped to the road and path network. The waypoints appear in the array in the order of the input coordinates, or in the order specified in the `destinations` query parameter. |

> **Note**
> 
> When a route is not found between a source and a destination, the corresponding value in the `durations` or `distances` matrix will be `null`.

#### Example response: Retrieve a matrix

```json
{
  "code": "Ok",
  "durations": [
    [0, 573, 1169.5],
    [573, 0, 597],
    [1169.5, 597, 0]
  ],
  "destinations": [
    {
      "name": "Mission Street",
      "location": [-122.418408, 37.751668],
      "distance": 5
    },
    {
      "name": "22nd Street",
      "location": [-122.422959, 37.755184],
      "distance": 8
    },
    {
      "name": "",
      "location": [-122.426911, 37.759695],
      "distance": 10
    }
  ],
  "sources": [
    {
      "name": "Mission Street",
      "location": [-122.418408, 37.751668],
      "distance": 5
    },
    {
      "name": "22nd Street",
      "location": [-122.422959, 37.755184],
      "distance": 8
    },
    {
      "name": "",
      "location": [-122.426911, 37.759695],
      "distance": 10
    }
  ]
}
```

### Matrix API errors

On error, the server responds with different HTTP status codes:

-   For responses with HTTP status codes lower than `500`, the JSON response body includes the `code` property, which may be used by client programs to manage control flow. The response body may also include a `message` property with a human-readable explanation of the error.
-   If a server error occurs, the HTTP status code will be `500` or higher and the response will not include a `code` property.

| Response body `code` | HTTP status code | Description |
| --- | --- | --- |
| `Ok` | `200` | Normal success case. |
| `NoRoute` | `200` | There was no route found for the given coordinates. Check for impossible routes (for example, routes over oceans without ferry connections) or incorrectly formatted coordinates. |
| null | `200` | Request contains both routable and unroutable coordinate pairs; "null" is returned for unroutable coordinate pairs only. |
| `Not Authorized - No Token` | `401` | No token was used in the query. |
| `Not Authorized - Invalid Token` | `401` | Check the access token you used in the query. |
| `Forbidden` | `403` | There may be an issue with your access token. |
| `ProfileNotFound` | `404` | Use a valid profile as described in [Retrieve a matrix](#retrieve-a-matrix). |
| `InvalidInput` | `422` | The given request was not valid. The `message` key of the response will hold an explanation of the invalid input. |