# Matrix

Travel times and distances between every pair in a set of up to 25 coordinates, in one call, for driving (with or without live traffic), walking, or cycling, from the [Matrix API](https://docs.mapbox.com/api/navigation/matrix/). The command also takes the common flags — `--username`/`-u`, `--token`/`-t`, `--profile`, `--id` — described in [Shared parameters](https://docs.mapbox.com/cli/reference/#shared-parameters).

This answers "how far or how long between every pair", not a route through every point in order: [`mapbox directions`](https://docs.mapbox.com/cli/reference/directions/) is a route through fixed stops, while a matrix is useful for ranking or filtering many candidates by reachability before committing to a route.

-   [`mapbox matrix`](#mapbox-matrix)

## `mapbox matrix`

A `durations` and/or `distances` matrix in row-major order — `durations[i][j]` is the time in seconds from source `i` to destination `j`; distances are in meters. Every coordinate is both a source and a destination unless `--sources` or `--destinations` narrows either side.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<routing-profile>` | Required. `mapbox/driving-traffic` (accounts for live traffic), `mapbox/driving`, `mapbox/walking`, or `mapbox/cycling`. Sent as typed rather than checked against a list, since some accounts have additional profiles of their own. |
| `<coordinates>` | Required. 2-25 `{longitude},{latitude}` pairs, semicolon-separated; at most 10 for `mapbox/driving-traffic`. |
| `--annotations` | Which matrix or matrices to return, comma-separated: `duration`, `distance`. Defaults to `duration` alone. |
| `--approaches` | Which side of the road to approach each coordinate from, semicolon-separated: `unrestricted` or `curb` per coordinate. |
| `--bearings` | An `{angle},{degrees}` per coordinate, semicolon-separated, filtering road segments by direction of travel. |
| `--sources` | Which coordinates are matrix rows: `all` (the default) or zero-based indices, **semicolon**-separated. Comma-separated indices are rejected. |
| `--destinations` | Which coordinates are matrix columns. Same rules as `--sources`. |
| `--fallback-speed` | Replaces a `null` (unreachable) cell with a straight-line estimate at this speed, in km/h, rather than leaving it `null`. |
| `--depart-at` | Departure time, ISO 8601, for future traffic conditions and time-dependent road restrictions. |

**Examples:**

```sh
mapbox matrix mapbox/driving "-122.42,37.78;-122.45,37.91;-122.41,37.80"
mapbox matrix mapbox/driving "-122.42,37.78;-122.45,37.91;-122.41,37.80" \
  --annotations duration,distance
mapbox matrix mapbox/driving "-122.42,37.78;-122.45,37.91;-122.41,37.80" \
  --sources 0 --destinations "1;2"
```