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. The command
also takes the common flags — --username/-u, --token/-t,
--profile, --id — described in
Shared parameters.
This answers "how far or how long between every pair", not a route through
every point in order: mapbox 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
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:
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"