Distance Matrix API | Travel Time & Distance

Guidelines for Developers

Introduction

Introduction

Requests

Requests

Responses

Responses

Introduction

Before you begin

Before you begin

What can you do with the Distance Matrix API?

What can you do with the Distance Matrix API?

Why use Distance Matrix API?

Why use Distance Matrix API?

How to use Distance Matrix API

How to use Distance Matrix API

Usage limits

Usage limits

Before you begin

It is an HTTP API service that is designed to calculate all possible combinations between the starting point and the destination and allows you to consider traffic congestion and a specific mode of transport. This travel time API is available anywhere in the world and ensures a similar level of accuracy and response with the best analogs like the google distance matrix API.

In this Distance Matrix API documentation, you can find an introduction for the product using and reference material on the available parameters.

This product ensures developers with a calculation of travel time and distance between some points. So, different types of delivery & courier services like food, goods, and medicine delivery have significant benefits from their use. Besides, you can use our API in route planning, logistics, and transportation, as well as in software development, real estate, and home and business services.

In particular, the product is critically helpful for taxi applications. It allows calculating the car delivery time while respecting traffic jams and congestion.

To choose the shortest route of the food delivery service from cafes and restaurants, our travel time API calculates the delivery time from each restaurant to the customer's address considering the road congestion.

You can use our product to find the destination point closest to the origin point or for any other purpose. The API will always return a duration and a distance on the fastest route for each element. In turn, each element is an origin-destination pair.

This solution works worldwide and is available for driving, walking, bicycling, and transit travel modes.

If real-time traffic does not affect your business significantly, you can save time and increase the product's performance by using its version without traffic monitoring. For large calculating volume, you can consider our Asynchronous Distance Matrix API.

You give input data (addresses or coordinates) for which you want to make an estimation. You will receive an answer in JSON format, and the response will contain information about the duration of each constructed route section. The calculated travel time for a route section always accounts for the current traffic conditions and the traffic forecast.

For example, there are three starting locations A, B, and C, and three destination locations E, B, and D. The Distance API returns the matrix of durations in seconds and distances in meters between the locations. It does not return route geometries.

↓ 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 time 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.

The following sections ensure you with more detailed information based on Distance Matrix API examples.

↓

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

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"
}

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"
}

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

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"
}

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"
}

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"
}

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