Estimate the distance and travel time between locations on a route

Given a list of origin-destination pairs and waypoints (stopovers) in between, the /geoservices/directions endpoint calculates the best route between each starting and end-point pair, while accounting for any waypoints and features to avoid, if specified. It returns the travel time and distance for each leg of the route (in other words, the first leg is from the starting point to the first waypoint, the second is from the first to second waypoint, and so on until the final waypoint to the end-point) considering driving a car as the default mode of transportation.

This endpoint can be used to estimate the travel times for resources traveling from home to various work items and then back to their home address.

Request the distance and time to travel between locations

  • Endpoint: /geoservices/directions
  • Operation: POST

Request parameters

Parameter Mandatory/optional Description
requests Mandatory An array of objects that contain an origin, destination, and (optionally) waypoints.
origin Mandatory The starting point for calculating the best travel distance and time in the form of latitude and longitude values. It doesn’t support other forms of location, such as Place ID or address.
destination Mandatory The finishing point for calculating the best travel distance and time in the form of latitude and longitude only.
waypoints Optional Intermediate locations that must be included in the route between the origin and destination, provided as latitude and longitude values. By default, the calulations use the waypoints in the order they are given. You can include up to 98 waypoints in a route.
avoid Optional Restrictions that must be adhered to when calculating the route. The following values are supported: ferry, highway, and toll.

For more information, please see the API documentation.

Example

This example shows how to find out how long it would take and what distance would be travelled when completing a day’s work, which consists of travelling from home to three different work sites and then back home.

Request

  • Endpoint: /geoservices/directions
  • Operation: POST
{
  "requests": [
    {
      "origin": {
				"lat": -27.4569042,
				"lng": 153.0349271
      },
      "destination": {
				"lat": -27.4569042,
				"lng": 153.0349271

      },
      "waypoints": [
        {
          "lat": -33.8894781,
          "lng": 151.1274125
				},
				{
					"lat": -27.472267, 
					"lng": 153.030608				
				},
				{
					"lat": -27.470468, 
					"lng": 153.023028
				},
				{
					"lat": -27.472696, 
					"lng": 153.017499
        }
      ]
    }
  ]
}

Response

This request returns the following information for each of the four legs of the journey:

{
	"result": {
		"routes": [
			[
				{
					"leg": {
						"origin": {
							"lat": -27.4569042,
							"lng": 153.0349271
						},
						"destination": {
							"lat": -33.8894781,
							"lng": 151.1274125
						},
						"avoid": []
					},
					"travelInfo": {
						"duration": {
							"durationInSeconds": 33481
						},
						"distance": {
							"distanceInMeters": 914432
						},
						"status": "OK"
					}
				},
				{
					"leg": {
						"origin": {
							"lat": -33.8894781,
							"lng": 151.1274125
						},
						"destination": {
							"lat": -27.472267,
							"lng": 153.030608
						},
						"avoid": []
					},
					"travelInfo": {
						"duration": {
							"durationInSeconds": 33423
						},
						"distance": {
							"distanceInMeters": 911537
						},
						"status": "OK"
					}
				},
				{
					"leg": {
						"origin": {
							"lat": -27.472267,
							"lng": 153.030608
						},
						"destination": {
							"lat": -27.470468,
							"lng": 153.023028
						},
						"avoid": []
					},
					"travelInfo": {
						"duration": {
							"durationInSeconds": 154
						},
						"distance": {
							"distanceInMeters": 1063
						},
						"status": "OK"
					}
				},
				{
					"leg": {
						"origin": {
							"lat": -27.470468,
							"lng": 153.023028
						},
						"destination": {
							"lat": -27.472696,
							"lng": 153.017499
						},
						"avoid": []
					},
					"travelInfo": {
						"duration": {
							"durationInSeconds": 207
						},
						"distance": {
							"distanceInMeters": 1707
						},
						"status": "OK"
					}
				},
				{
					"leg": {
						"origin": {
							"lat": -27.472696,
							"lng": 153.017499
						},
						"destination": {
							"lat": -27.4569042,
							"lng": 153.0349271
						},
						"avoid": []
					},
					"travelInfo": {
						"duration": {
							"durationInSeconds": 427
						},
						"distance": {
							"distanceInMeters": 4007
						},
						"status": "OK"
					}
				}
			]
		]
	}
}