Distance Matrix API | Travel Time & Distance

What can you do with the Distance Matrix API?

Why use Distance Matrix API?

How to use Distance Matrix API

How to use Distance Matrix API through Postman

• To get started with Postman, install it on your computer or access a browser web version.
  
• Import our pre-configured API collection:
  
  • 
    Open Postman
    
  • 
    Click on the “Import” button in the top left corner.
    
  • 
    Select “Import from link” and paste this Postman collection link: https://www.postman.com/distancematrix/workspace/distance-matrix/overview
    
• Upon importing, Postman will automatically add the collection into your workspace.
  
• For users of the online version of Postman, you can directly open the collection link and create a fork. Do this by clicking on the three dots next to the collection name.
  
• Set up your environment in Postman, go to the Variables section and add your authentication token in the “API Authorization Token” field. 
  
• Don't forget to save these changes.
  
• Make your first request: Select an endpoint from our collection, configure your request parameters, and hit send to see the response.
  

Request Parameters

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>

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

Required Parameters

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>

{
    "destination_addresses": [
        "St John's Church, North End Rd, London SW6 1PB, United Kingdom"
    ],
    "origin_addresses": [
        "Westminster Abbey, 20 Deans Yd, London SW1P 3PA, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.3 km",
                        "value": 7346
                    },
                    "duration": {
                        "text": "23 mins",
                        "value": 1401
                    },
                    "origin": "Westminster Abbey, 20 Deans Yd, Westminster, London SW1P 3PA, United Kingdom",
                    "destination": "St John's Church, North End Rd, Fulham, London SW6 1PB, United Kingdom",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

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.
    

• 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.
  

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>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "166.4 km",
                        "value": 166409
                    },
                    "duration": {
                        "text": "4 hour 2 mins",
                        "value": 14524
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "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.
    

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>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "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. Affects the field in the distance_in_traffic_model response, returning the shortest route.
    
  • 
    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. Affects the field in the distance_in_traffic_model response, returning the shortest route.
    

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>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "4 hour 0 mins",
                        "value": 14400
                    },
                    "distance_in_traffic_model": {
                        "text": "118 miles",
                        "value": 189274
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "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.
    
  • 
    tram indicates that the calculated route should prefer travel by tram and light rail.
    
  • 
    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.
    

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>

{
    "destination_addresses": [
        "Raw Network, Sherborne B16 8FN, United Kingdom"
    ],
    "origin_addresses": [
        "Giaralis Karavasilis Tsavdaridis, 49 The Mall, London N14 6LR, United Kingdom"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "207.3 km",
                        "value": 207323
                    },
                    "duration": {
                        "text": "2 hour 27 mins",
                        "value": 8844
                    },
                    "duration_in_traffic": {
                        "text": "2 hour 29 mins",
                        "value": 8968
                    },
                    "origin": "51.507033,-0.1277161",
                    "destination": "52.486243,-1.890401",
                    "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).
  
• 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.
  

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>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "5.7 km",
                        "value": 5699
                    },
                    "duration": {
                        "text": "1 hour 12 mins",
                        "value": 4379
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "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.
  

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>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "23 mins",
                        "value": 1395
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Restrictions

• avoid=tolls
  
• avoid=highways
  
• avoid=ferries
  
• avoid=indoor
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&mode=driving&departure_time=now&avoid=ferries&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Unit Systems

• units=metric (default) returns distances in kilometers and meters.
  
• units=imperial returns distances in miles and feet.
  

https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&departure_time=now&units=imperial&key=<your_access_token>

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "4.7 mi",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "duration_in_traffic": {
                        "text": "26 mins",
                        "value": 1568
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Response example

{
    "destination_addresses": [
        "Westminster Abbey, London SW1P 3PA, UK"
    ],
    "origin_addresses": [
        "Chapel, London SW6 1BA, UK"
    ],
    "rows": [
        {
            "elements": [
                {
                    "distance": {
                        "text": "7.6 km",
                        "value": 7567
                    },
                    "duration": {
                        "text": "22 mins",
                        "value": 1359
                    },
                    "origin": "51.4822656,-0.1933769",
                    "destination": "51.4994794,-0.1269979",
                    "status": "OK"
                }
            ]
        }
    ],
    "status": "OK"
}

Distance Matrix Response Elements

• status contains metadata on the request. See Status Codes below.
  
• origin_addresses contain an array of addresses as returned by the API from your original request. These are formatted by the geocoder and localized according to the language parameter passed with the request.
  
• destination_addresses contain an array of addresses returned by the API from your initial request. As with origin_addresses, these are localized if appropriate.
  
• rows contain an array of elements, which in turn contain status, duration, and distance element.
  

Status Codes

Top-level Status Codes

• OK indicates the response contains a valid result.
• INVALID_REQUEST indicates that the provided request was invalid.
• MAX_ELEMENTS_EXCEEDED indicates that the product of origin and destination exceeds the per-query limit.
• OVER_DAILY_LIMIT indicates any of the following:
  
  • 
    The API key is missing or invalid.
    
  • 
    Billing has not been enabled on your account.
    
  • 
    A self-imposed usage cap has been exceeded.
    
  • 
    The provided method of payment is no longer valid (for example, a credit card has expired).
    
• OVER_QUERY_LIMIT indicates the service has received too many requests from your application within the allowed time period.
• REQUEST_DENIED indicates that the service denied the use of the Distance Matrix service by your application.
• UNKNOWN_ERROR indicates a Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.

Element-level Status Codes

• OK indicates the response and contains a valid result.
  
• NOT_FOUND indicates that the origin and/or destination of this pairing could not be geocoded.
  
• ZERO_RESULTS indicates that no route could be found between the origin and destination.
  
• MAX_ROUTE_LENGTH_EXCEEDED indicates that the requested route is too long and cannot be processed.
  
• UNKNOWN_ERROR indicates a Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.
  

Error Messages

Rows

Elements

• status: See Status Codes for a list of possible status codes.
  
• duration: The length of time it takes to travel this route, expressed in seconds (the value field) and as text.
  
• duration_in_traffic: The length of time it takes to travel this route, based on current and historical traffic conditions.
  
• distance: The total distance of this route, expressed in meters (value) and as text. The textual value uses the unit system specified with the unit parameter of the original request, or the origin's region.
  
• distance_in_traffic_model: The shortest distance needed to travel this route, based on current and historical traffic conditions.