Calculate the travel time and distance between multiple locations

The /geoservices/distanceMatrix endpoint can be used to calculate the distance and time it takes to travel between a matrix of origins and destinations. The values are from the best travel route for each origin and destination pair using driving as the default mode of transportation. Different map service providers use different factors to evaluate the best route, however, traffic conditions are not taken into account by any of the vendors when using this endpoint.

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.

Request the travel time between locations

  • Endpoint: /geoservices/distanceMatrix
  • Operation: POST

Request parameters

Parameter Mandatory/optional Description
origins Mandatory One or more starting locations for the travel route calculations in the form of geographic co-ordinates (latitude and longitude). Other forms of location, like the Place ID or address, are not supported.
destinations Mandatory One or more end-point locations for the travel route calculations. As with origins, their latitude and longitudes must be provided and no other location formats are supported.

For more information, please see the API documentation.

Example

This example shows how to compare two different starting locations (for example, the home addresses of two resources) to see which would be the fastest to get to one of three different work locations.

  • Endpoint: /geoservices/distanceMatrix
  • Operation: POST
  {
    "origins": [
      {
        "lat": -27.4572735,
        "lng": 153.0362663
      },
			{
			  "lat": -27.466484, 
			  "lng": 153.025168
			}
    ],
    "destinations": [
      {
        "lat": -27.353639,
        "lng": 152.9684713
			},
			{
				"lat": -27.475227, 
				"lng": 153.027641
			},
			{
				"lat": -27.474112, 
				"lng": 152.976175
      }
    ]
  }

This request returns the following information:

{
	"result": {
		"matrix": [
			[
				{
					"duration": {
						"durationInSeconds": 1145
					},
					"distance": {
						"distanceInMeters": 17168
					},
					"status": "OK"
				},
				{
					"duration": {
						"durationInSeconds": 338
					},
					"distance": {
						"distanceInMeters": 2513
					},
					"status": "OK"
				},
				{
					"duration": {
						"durationInSeconds": 666
					},
					"distance": {
						"distanceInMeters": 7722
					},
					"status": "OK"
				}
			],
			[
				{
					"duration": {
						"durationInSeconds": 1237
					},
					"distance": {
						"distanceInMeters": 16879
					},
					"status": "OK"
				},
				{
					"duration": {
						"durationInSeconds": 182
					},
					"distance": {
						"distanceInMeters": 1625
					},
					"status": "OK"
				},
				{
					"duration": {
						"durationInSeconds": 521
					},
					"distance": {
						"distanceInMeters": 5998
					},
					"status": "OK"
				}
			]
		],
		"vendor": "GRAPHHOPPER"
	}
}

The response lists the duration (by driving and not factoring in traffic) and distance between each origin with each destination. From this response, the resource at the first location would have the least travel time to get to the first work location, but the second would take less time to get to the other locations from thier starting point.

The/geoservices/distanceMatrix API documentation