Solutions
Developer guide
Pricing
Sign in
Get a free trial
Products
Solutions
Cases
Developer guide
Pricing
Contact us
Contact us
The Geocoding API (Beta)
The Distance Matrix API
The Geocoding API (Beta)

Guidelines for Developers

The Distance Matrix API

Introduction
Introduction
Requests
Requests
Responses
Responses
Introduction
Before you begin
Before you begin
Usage limits
Usage limits
Before you begin
This document is intended for developers who wish to compute travel distance and time between some points. It provides an introduction to using the API and reference material on the available parameters.

The Distance Matrix API is an HTTP API service that provides travel distance and time for a location matrix. Calculations are made for all possible combinations between the starting point to the destination. The API returns information that is based on the recommended route between the start and end points, as calculated by the Distance Matrix API, and consists of rows containing duration and distance values for each pair. Time periods are based on predictive traffic information, depending on the start time specified in the request.

The API response contains a distance matrix in JSON format, as well as information about the duration of each constructed route section in the matrix. The calculated travel time for a route section always accounts for the current traffic conditions and the traffic forecast. The Distance Matrix API works worldwide and is available for driving, walking, bicycling and transit travel modes.

You can use the API to find the destination point that is the closest to the point of origin or for any other purpose. The Matrix API will always return a duration and a distance on the fastest route for each element in the matrix, where an element is an origin-destination pair in the matrix.

For example, there are three starting locations A, B, and C, and three destination locations E, B, and D, the Matrix API will return the matrix of all travel time in seconds and distances in meters between the locations:
↓ origins \ destinations
E
B
D
A
A to E
A to B
A to D
B
B to E
B to B = 0
B to D
C
C to E
C to B
C to D
The Matrix API returns durations in seconds and distances in meters. It does not return route geometries.

The Duration and distance between points may not be symmetric, since the routes may differ by direction due to one-way streets or turn restrictions. For example, A to B may have a different duration than B to A.
Distance Matrix Requests
Request Parameters
Request Parameters
Required Parameters
Required Parameters
Optional Parameters
Optional Parameters
Traffic Information
Traffic Information
Restrictions
Restrictions
Unit Systems
Unit Systems
Travel Modes
Travel Modes
Request Parameters
The Distance Matrix API request was created specifically to be similar to the Google Distance Matrix API request format. You can get more information on the Migrate to DistanceMatrix.ai API page.
A Distance Matrix API request takes the following form:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json
?origins=<origin_location_1|origin_location_2|...|origin_location_n>
&destinations=<destination_location_1|destination_location_2|...|destination_location_n>
&key=<your_access_token>
A Distance Matrix API request example:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>
Request Parameters
The Distance Matrix API request was created specifically to be similar to the Google Distance Matrix API request format. You can get more information on the Migrate to DistanceMatrix.ai API page.
A Distance Matrix API request takes the following form:
GET:
https://api.distancematrix.ai/maps/api/ distancematrix/json?origins=<origin_location_1|origin_location_2 |...|origin_location_n>&destinations= <destination_location_1|destination_location_2 |...|destination_location_n>
&key=<your_access_token>
A Distance Matrix API request example:
GET:
https://api.distancematrix.ai/maps/api/ distancematrix/json?origins= 51.4822656,-0.1933769&destinations= 51.4994794,-0.1269979&key=<your_access_token>
Required Parameters
origins — a starting point for calculating travel distance and time. You can supply one or more locations separated by the pipe character (|) in the form of an address or latitude/longitude coordinates:
1. If you pass an address, the service geocodes the string and converts it to a latitude/longitude coordinate to calculate the distance. This coordinate may be different from that returned by the Geocoding API, for example, a building entrance rather than its center.
Show example
Hide example
Show example
Example request with addresses:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom&destinations=St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom&key=<your_access_token>
Response
BODY
{
\t "destination_addresses": [
&nbsp; "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom"
],
"origin_addresses": [
"Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "6.5 km",
"value": 6477
},
"duration": {
"text": "21 min",
"value": 1287
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom" ], "origin_addresses": [ "Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom" ], "rows": [ { "elements": [ { "distance": { "text": "6.5 km", "value": 6477 }, "duration": { "text": "21 min", "value": 1287 }, "status": "OK" } ] } ], "status": "OK" }
2. If you pass latitude/longitude coordinates, they are used unchanged to calculate distance. Ensure that no space exists between the latitude and longitude values.
Show example
Hide example
Show example
Example request with coordinates:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979
&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Westminster Abbey, Westminster, London SW1P 3PA, UK"
],
"origin_addresses": [
"Chapel, Fulham, London SW6 1BA, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "7.6 km",
"value": 7561
},
"duration": {
"text": "22 min",
"value": 1303
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom" ], "origin_addresses": [ "Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom" ], "rows": [ { "elements": [ { "distance": { "text": "6.5 km", "value": 6477 }, "duration": { "text": "21 min", "value": 1287 }, "status": "OK" } ] } ], "status": "OK" }
destinations — one or more locations to use as the final destination for calculating travel distance and time. The options for the destination parameter are the same as for the original parameter, as described above.
key — the API key of your application
Optional Parameters
mode (defaults to driving) — specifies the mode of transport to use when calculating distance. Valid values and other request details are specified in the Travel Modes section of this document.
language — a language that is used to return results.
See the list of supported languages.
If language is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header, or the native language of the domain from which the request is sent.
The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
If a name is not available in the preferred language, the API uses the closest match.
The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.
Show languages
Hide languages
Show languages
Language Code
Language
Language Code
Language
af
Afrikaans
ja
sq
Albanian
kn
Kannada
am
Amharic
kk
Kazakh
Japanese
ar
Arabic
km
hy
Armenian
ko
Korean
az
Azerbaijani
ky
Kyrgyz
Khmer
eu
Basque
lo
be
Belarusian
lv
Latvian
bn
Bengali
lt
Lithuanian
Lao
bs
Bosnian
mk
bg
Bulgarian
ms
Malay
my
Burmese
ml
Malayalam
Macedonian
ca
Catalan
mr
zh
Chinese
mn
Mongolian
zh-CN
Chinese (Simplified)
ne
Nepali
Marathi
zh-HK
Chinese (Hong Kong)
no
zh-TW
Chinese (Traditional)
pl
Polish
hr
Croatian
pt
Portuguese
Norwegian
cs
Czech
pt-BR
da
Danish
pt-PT
Portuguese (Portugal)
nl
Dutch
pa
Punjabi
Portuguese (Brazil)
en
English
ro
en-AU
English (Australian)
ru
Russian
en-GB
English (Great Britain)
sr
Serbian
Romanian
et
Estonian
si
Sinhalese
fa
Farsi
sk
Slovak
fi
Finnish
sl
fil
Filipino
es
Spanish
fr
French
es-419
Spanish (Latin America)
Slovenian
fr-CA
French (Canada)
sw
gl
Galician
sv
Swedish
ka
Georgian
ta
Tamil
Swahili
de
German
te
el
Greek
th
Thai
gu
Gujarati
tr
Turkish
Telugu
iw
Hebrew
uk
hi
Hindi
ur
Urdu
hu
Hungarian
uz
Uzbek
Ukrainian
is
Icelandic
vi
id
Indonesian
zu
Zulu
it
Italian
Vietnamese
avoid — introduces restrictions to the route. Valid values are specified in the Restrictions section of this document. Only one restriction can be specified.
units — specifies the unit system to use when expressing distance as text. See the Unit Systems section of this document for more information.
arrival_time — specifies the desired time of arrival for transit requests, in seconds since midnight, January 1, 1970, UTC. You can specify either departure_time or arrival_time, but not both. Note that arrival_time must be specified as an integer
Show example
Hide example
Show example
Request example with arrival_time:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401
&arrival_time=now&transit_mode=bus&mode=transit&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Birmingham B4 7DL, UK"
],
"origin_addresses": [
"Whitehall, Westminster, London, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "202.4 km",
"value": 202400
},
"duration": {
"text": "2 h 20 min",
"value": 8421
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "Birmingham B4 7DL, UK" ], "origin_addresses": [ "Whitehall, Westminster, London, UK" ], "rows": [ { "elements": [ { "distance": { "text": "202.4 km", "value": 202400 }, "duration": { "text": "2 h 20 min", "value": 8421 }, "status": "OK" } ] } ], "status": "OK" }
departure_time — a desired time of the departure. You can specify the time as an integer in seconds since midnight, January 1, 1970, UTC. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). The departure_time must be set to the current time or some time in the future. It cannot be in the past. Results for a given request may vary over time due to the changes in the road network, updated average traffic conditions, and the distributed nature of the service. Results may also vary between nearly-equivalent routes at any time or frequency. The departure time may be specified in two cases:
For requests where the travel mode is transit: You can optionally specify one of departure_time or arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time).
For requests where the travel mode is driving: You can specify the departure_time to receive a route and trip duration (response field: duration_in_traffic) that take traffic conditions into account. The departure_time must be set to the current time or some time in the future. It cannot be in the past.
* Note: If departure time is not specified, choice of route and duration are based on road network and average time-independent traffic conditions. Results for a given request may vary over time due to changes in the road network, updated average traffic conditions, and the distributed nature of the service. Results may also vary between nearly-equivalent routes at any time or frequency.
Show example
Hide example
Show example
Example request with departure_time:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401
&departure_time=now&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Birmingham B4 7DL, UK"
],
"origin_addresses": [
"Whitehall, Westminster, London, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "202.4 km",
"value": 202399
},
"duration": {
"text": "2 h 18 min",
"value": 8294
},
"duration_in_traffic": {
"text": "2 hour 0 mins",
"value": 7200
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "Birmingham B4 7DL, UK" ], "origin_addresses": [ "Whitehall, Westminster, London, UK" ], "rows": [ { "elements": [ { "distance": { "text": "202.4 km", "value": 202400 }, "duration": { "text": "2 h 20 min", "value": 8421 }, "status": "OK" } ] } ], "status": "OK" }
traffic_model (defaults to best_guess) — specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration_in_traffic field in the response, which contains the predicted time in traffic based on historical averages. The traffic_model parameter may only be specified for requests where the travel mode is driving, and where the request includes a departure_time. The available values for this parameter are:
best_guess (default) indicates that the returned duration_in_traffic should be the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departure_time is to now.
pessimistic indicates that the returned duration_in_traffic should be longer than the actual travel time on most days, though occasional days with particularly bad traffic conditions may exceed this value.
optimistic indicates that the returned duration_in_traffic should be shorter than the actual travel time on most days, though occasional days with particularly good traffic conditions may be faster than this value.
Show example
Hide example
Show example
Example request with traffic_model:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401
&traffic_model=pessimistic&departure_time=now&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Birmingham B4 7DL, UK"
],
"origin_addresses": [
"Whitehall, Westminster, London, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "202.4 km",
"value": 202400
},
"duration": {
"text": "2 h 20 min",
"value": 8421
},
"duration_in_traffic": {
"text": "3 hour 0 mins",
"value": 10800
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "Birmingham B4 7DL, UK" ], "origin_addresses": [ "Whitehall, Westminster, London, UK" ], "rows": [ { "elements": [ { "distance": { "text": "202.4 km", "value": 202400 }, "duration": { "text": "2 h 20 min", "value": 8421 }, "duration_in_traffic": { "text": "3 hour 0 mins", "value": 10800 }, "status": "OK" } ] } ], "status": "OK" }
transit_mode — specifies one or more preferred modes of transit. This parameter may only be specified for requests where the mode is transit. The parameter supports the following arguments:
bus indicates that the calculated route should prefer travel by bus.
subway indicates that the calculated route should prefer travel by subway.
train indicates that the calculated route should prefer travel by train.
subway indicates that the calculated route should prefer travel by subway.
rail indicates that the calculated route should prefer travel by train, tram, light rail, and subway. This is equivalent to transit_mode=train|tram|subway.
Show example
Hide example
Show example
Request example with arrival_time:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.507033,-0.1277161&destinations=52.486243,-1.890401
&transit_mode=bus|train|tram|subway&mode=transit&departure_time=now&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Birmingham B4 7DL, UK"
],
"origin_addresses": [
"Whitehall, Westminster, London, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "202.4 km",
"value": 202399
},
"duration": {
"text": "2 h 20 min",
"value": 8421
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "Birmingham B4 7DL, UK" ], "origin_addresses": [ "Whitehall, Westminster, London, UK" ], "rows": [ { "elements": [ { "distance": { "text": "202.4 km", "value": 202400 }, "duration": { "text": "2 h 20 min", "value": 8421 }, "status": "OK" } ] } ], "status": "OK" }
Travel Modes
driving (default) indicates distance calculation using the road network.
walking requests distance calculation for walking via pedestrian paths & sidewalks (where available).
For the calculation of distances, you may specify the transportation mode to use. By default, distances are calculated for the driving mode. The following travel modes are supported:
bicycling requests distance calculation for bicycling via bicycle paths & preferred streets (where available).
transit requests distance calculation via public transit routes (where available). If you set the mode to transit you need specify either a departure_time or an arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time). You need also include a transit_mode.
Show example
Hide example
Show example
Example request with travel modes:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979
&mode=walking&departure_time=now&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Westminster Abbey, Westminster, London SW1P 3PA, UK"
],
"origin_addresses": [
"Chapel, Fulham, London SW6 1BA, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "6.2 km",
"value": 6187
},
"duration": {
"text": "1 h 19 min",
"value": 4723
},
"status": "OK"
}
]
}
],
"status": "OK"
}
{ "destination_addresses": [ "Westminster Abbey, Westminster, London SW1P 3PA, UK" ], "origin_addresses": [ "Chapel, Fulham, London SW6 1BA, UK" ], "rows": [ { "elements": [ { "distance": { "text": "6.2 km", "value": 6187 }, "duration": { "text": "1 h 19 min", "value": 4723 }, "status": "OK" } ] } ], "status": "OK" }
Traffic Information
The travel mode parameter is driving, or it is not specified (driving is the default travel mode).
The request includes a valid departure_time parameter. The departure_time can be set to the current time or some other time.
Traffic information is used when all the following apply (these are the conditions required to receive the duration_in_traffic field in the Distance Matrix response):
Optionally, you can include the traffic_model parameter in your request to specify the assumptions to use when calculating time in traffic.
Show example
Hide example
Show example
Example request with traffic information:
GET:
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979
&mode=driving&departure_time=now&key=<your_access_token>
Response
BODY
{
"destination_addresses": [
"Westminster Abbey, Westminster, London SW1P 3PA, UK"
],
"origin_addresses": [
"Chapel, Fulham, London SW6 1BA, UK"
],
"rows": [
{
"elements": [
{
"distance": {
"text": "7.6 km",
"value": 7561
},
"duration": {
"text": "20 min",
"value": 1205
},
"duration_in_traffic": {
"text": "16 mins",
"value": 960
},
"status": "OK"
}
]
}
],
"status": "OK"
}