Matrix API

📘
Distances are not the shortest distance between two coordinates, but rather the distances of the fastest routes.

Request

Request Format

https://us1.locationiq.com/v1/matrix/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&sources={elem1};{elem2};..&destinations={elem1};{elem2};...&annotations={duration|distance|duration,distance}

Example Request

Returns a 3x3 duration matrix:

https://us1.locationiq.com/v1/matrix/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>

Returns a 1x3 duration matrix

https://us1.locationiq.com/v1/matrix/driving/-0.127627,51.503355;-0.087199,51.509562;-0.142001,51.501284?sources=0&key=<YOUR_ACCESS_TOKEN>

Returns a 3x3 duration matrix and a 3x3 distance matrix:

https://us1.locationiq.com/v1/matrix/driving/-0.127627,51.503355;-0.087199,51.509562;-0.142001,51.501284?annotations=distance,duration&key=<YOUR_ACCESS_TOKEN>

Request Parameters

In addition to the general options the following options are supported for this service:

Option	Values	Description
sources	`{index};{index}[;{index} ...]` or `all` (default)	Use location with given index as source.
destinations	`{index};{index}[;{index} ...]` or `all` (default)	Use location with given index as destination.
annotations	`duration` (default), `distance`, or `duration,distance`	Return the requested matrix in response.
fallback_speed	`double > 0`	If no route found between a source/destination pair, calculate the as-the-crow-flies distance, then use this speed to estimate duration.
fallback_coordinate	`input` (default), or `snapped`	When using a `fallback_speed`, use the user-supplied coordinate (`input`), or the snapped location (`snapped`) for calculating distances.

Unlike other array encoded options, the length of sources and destinations can be smaller or equal
to number of input locations;

Example:

sources=0;5;7&destinations=5;1;4;2;3;6

Element	Values
index	`0 <= integer < #locations`

Response

Response Example

{
    "code": "Ok",
    "distances": [
        [0, 3833.6, 1552.8],
        [3763.8, 0, 4963],
        [1622.7, 4953.2, 0]
    ],
    "durations": [
        [0, 529, 185.7],
        [472.3, 0, 622.4],
        [197.7, 663.1, 0]
    ],
    "sources": [{
        "hint": "dRJAiW_vt4sOAAAAAAAAAAAAAAAAAAAA1kBzQQAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAAAAAAAAIFwEAIhL-_zzgEQN1Df7_--ARAwAAzxB42O4j",
        "distance": 85.752389,
        "location": [-0.12643, 51.503164],
        "name": "Downing Street"
    }, {
        "hint": "BdAMgP___38BAAAAKAAAAFsAAAC7AAAAdwJqP1dc30EhbYFCWlnxQgEAAAAoAAAAWwAAALsAAAAIFwEAYKv-_zr5EQNhq_7_OvkRAwQA3wB42O4j",
        "distance": 0.069405,
        "location": [-0.0872, 51.509562],
        "name": "King William Street"
    }, {
        "hint": "inUjk411I5MAAAAADwAAAF0AAAAfAQAAAAAAAIdkSEB2P51Ba9xvQgAAAAAHAAAAMAAAAJEAAAAIFwEARdb9__DVEQNP1f3_5NgRAwYAXwV42O4j",
        "distance": 85.827043,
        "location": [-0.141755, 51.500528],
        "name": "Ambassador's Court"
    }],
    "destinations": [{
        "hint": "dRJAiW_vt4sOAAAAAAAAAAAAAAAAAAAA1kBzQQAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAAAAAAAAIFwEAIhL-_zzgEQN1Df7_--ARAwAAzxB42O4j",
        "distance": 85.752389,
        "location": [-0.12643, 51.503164],
        "name": "Downing Street"
    }, {
        "hint": "BdAMgP___38BAAAAKAAAAFsAAAC7AAAAdwJqP1dc30EhbYFCWlnxQgEAAAAoAAAAWwAAALsAAAAIFwEAYKv-_zr5EQNhq_7_OvkRAwQA3wB42O4j",
        "distance": 0.069405,
        "location": [-0.0872, 51.509562],
        "name": "King William Street"
    }, {
        "hint": "inUjk411I5MAAAAADwAAAF0AAAAfAQAAAAAAAIdkSEB2P51Ba9xvQgAAAAAHAAAAMAAAAJEAAAAIFwEARdb9__DVEQNP1f3_5NgRAwYAXwV42O4j",
        "distance": 85.827043,
        "location": [-0.141755, 51.500528],
        "name": "Ambassador's Court"
    }]
}

Response Parameters

code: if the request was successful Ok otherwise see the service dependent and general status codes.
durations: array of arrays that stores the matrix in row-major order. durations[i][j] gives the travel time from
the i-th waypoint to the j-th waypoint. Values are given in seconds. Can be null if no route between i and j can be found.
distances: array of arrays that stores the matrix in row-major order. distances[i][j] gives the travel distance from
the i-th waypoint to the j-th waypoint. Values are given in meters. Can be null if no route between i and j can be found.
sources: array of Waypoint objects describing all sources in order
destinations: array of Waypoint objects describing all destinations in order

In case of error the following codes are supported in addition to the general ones:

Type	Description
`NoTable`	No route found.
`NotImplemented`	This request is not supported

All other properties might be undefined.