Distance Matrix API

Calculating the distance between two locations: Distance Matrix API

The /distanceMatrix endpoint calculates the travel duration and travel distance for a matrix of origins and destinations. It provides the best travel route for each set of origin and destination by considering driving as the default mode of transportation. Based on the map service providers (Google or GraphHopper), there can be different factors taken under consideration to calculate the best route. However, the traffic condition is not taken into account by this API irrespective of the vendor used.

Please note that there are limits on the total number elements that can be requested and that large requests (where origins * destinations > 1000) may take several seconds to compute. These limits may vary depending on your underlying configuration as well.

Mandatory parameters

  1. origins: It is the starting point for calculating travel distance and time. You must provide the origins in the form latitude/longitude coordinates. It doesn’t support other form of location like the place ID or an address.

  2. destinations: It is the finishing point for calculating travel distance and time. Just like with the origins, You must provide the destinations in the form latitude/longitude coordinates. It doesn’t support other form of location like the place ID or an address.

When you pass latitude/longitude coordinates of a place, please note that they could be snapped to the coordinates of the nearest road.

For example, let’s say you have to pick up your new laptop from a store nearby. You want to find the best possible driving route from your home in Fortitude Valley, Brisbane to your store in Albany Creek, Brisbane. In this case, you can send a POST request by calling the /distanceMatrix endpoint with the following payload:


  {
    "origins": [
      {
        "lat": -27.4572735,
        "lng": 153.0362663
      }

    ],
    "destinations": [
      {
        "lat": -27.353639,
        "lng": 152.9684713
      }
    ]
  }

This request returns the following information :

{
    "result": {
        "matrix": [
            [
                {
                    "duration": {
                        "durationInSeconds": 1136
                    },
                    "distance": {
                        "distanceInMeters": 17117
                    },
                    "status": "OK"
                }
            ]
        ],
        "vendor": "GRAPHHOPPER"
    }
}

From the response, you can see that the driving time and distance via the optimal route to travel from Fortitude Valley and Albany Creek, Brisbane is 1136 seconds and 17117 meters respectively.

For the schema information of this endpoint, please refer to /distanceMatrix.