Matrix
Travel-time and distance matrices.
Travel-time and distance matrix
Computes travel times (durations), distances, or both, from every source to every destination.
You send your points once in locations, then choose which of them are sources and which are
destinations.
What it costs
The number of sources times the number of destinations. Put another way, elements consumed =
|sources| × |destinations|.
If you leave out sources, or send ["all"], every location is used as a source. The same goes
for destinations. So a request with n locations that sets neither field costs n² elements.
Limits
| Plan | Largest matrix per request |
|---|---|
| Free | 2,500 elements (50 × 50) |
| Every other plan | 90,000 elements (300 × 300) |
A bigger request is refused before any work is done, with 400 (code 6004, matrix too large).
Requests with certain options
Five options make a matrix much slower to compute, so requests using them also have a limit on the number of sources.
The five are avoid_borders, avoid_polygons, avoid_countries, avoid_features and
dynamic_speeds. The value doesn't matter: "dynamic_speeds": false counts the same as
true. Sending "optimized": false without an options block counts too, because it asks
for the same slower work.
An empty options, "options": null, and an options block holding only other fields are
not affected by this limit.
How many sources you may send depends on your plan:
| Plan | Matrix with these options | If you go over |
|---|---|---|
| Free | Not allowed | 403 (code 5011) |
| Every other plan | Up to 25 sources | 400 (code 6004), with a message that names the limit |
The number of sources is the length of sources when it lists location indices, counting
repeats; otherwise it is the number of locations. The element limit above still applies to
these requests.
A 5011 refusal has the same error text as an invalid key
({"error":"Access to this API has been disallowed","code":5011}), so check code to tell them
apart.
When one of these requests runs out of searching
A matrix using those options searches the road network once per source, and there is a
ceiling on how much searching a single request may do. A request that reaches it fails with
500 (code 6020), partway through. You aren't charged for it.
Send fewer sources, or cover a smaller area. This ceiling is not a plan limit, so a larger plan does not lift it.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Travel-time and distance matrix › Request Body
locationsThe points the matrix is computed over. At least two.
sourcesIndices into locations to use as sources. Leave it out, or send ["all"], to use
every location. Cost is |sources| × |destinations|.
destinationsIndices into locations to use as destinations. Leave it out, or send ["all"], to
use every location. Cost is |sources| × |destinations|.
metricsWhich matrices to return. Defaults to durations only.
resolve_locationsReturn the name of the nearest road for each snapped point.
unitsUnits for the distance matrix. Durations are always seconds.
idAn arbitrary identifier echoed back in the response metadata.
Travel-time and distance matrix › Responses
The computed matrix.
durationsTravel times in seconds, as rows of sources by columns of destinations. A null
entry means no route was found between that pair.
distancesDistances, present only when requested via metrics.
Details about the request and the data behind the answer, plus element_count.
Travel-time and distance matrix (explicit JSON form)
Identical to POST /v2/matrix/{profile}.
path Parameters
profileThe routing profile. Only driving-car is served. Any other value returns an
"incorrect value" error.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Travel-time and distance matrix (explicit JSON form) › Request Body
locationsThe points the matrix is computed over. At least two.
sourcesIndices into locations to use as sources. Leave it out, or send ["all"], to use
every location. Cost is |sources| × |destinations|.
destinationsIndices into locations to use as destinations. Leave it out, or send ["all"], to
use every location. Cost is |sources| × |destinations|.
metricsWhich matrices to return. Defaults to durations only.
resolve_locationsReturn the name of the nearest road for each snapped point.
unitsUnits for the distance matrix. Durations are always seconds.
idAn arbitrary identifier echoed back in the response metadata.
Travel-time and distance matrix (explicit JSON form) › Responses
The computed matrix.
durationsTravel times in seconds, as rows of sources by columns of destinations. A null
entry means no route was found between that pair.
distancesDistances, present only when requested via metrics.
Details about the request and the data behind the answer, plus element_count.