Back to Website
Guides
Dashboard

Matrix API

Computes duration of the fastest route between all pairs of supplied coordinates. Returns the durations or distances or both between the coordinate pairs.

Suggest Edits

📘

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

Request

Request Format

❗️

Coordinate Order

When using our Routing APIs, the order of coordinates should be entered as longitude,latitude instead of the typical latitude,longitude 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:

OptionValuesDescription
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.
annotationsduration (default), distance, or duration,distanceReturn the requested matrix in response.
fallback_speeddouble > 0If no route found between a source/destination pair, calculate the as-the-crow-flies distance, then use this speed to estimate duration.
fallback_coordinateinput (default), or snappedWhen 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

ElementValues
index0 <= 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:

TypeDescription
NoTableNo route found.
NotImplementedThis request is not supported

All other properties might be undefined.

Updated 5 months ago