Find directions between two locations
Find directions between two locations: Directions API
Given a list of origin/destination pairs and waypoints (stopovers) in between, the /directions
endpoint calculates the direction between the source and destination for each pair while accounting for the multiple waypoints en route if any. It calculates the best travel route, and returns the travel time and distance for the given origins, destinations and waypoints by considering car (driving) as the default mode of transportation.
Mandatory parameters
-
requests
: Therequests
accepts an array of objects that comprises of origin, destination and waypoints.-
origin: It is the starting point for calculating the best travel distance and time. You must provide the
origin
in the form latitude/longitude coordinates. It doesn’t support other form of location like the place ID or an address. -
destination: It is the finishing point for calculating the best travel distance and time. Just like with the
origin
, you must provide thedestination
in the form latitude/longitude coordinates. It doesn’t support other form of location like the place ID or an address. -
waypoints: They are different intermediate locations that are included in the route between the origin and destination as a pass through or stopover locations. The
waypoints
should also be in the form of latitude/longitude coordinates. By default, the Directions API calculates the best route using the waypoints in the order they are given. You can include up to 98 waypoints in a route. Within therequest
, thewaypoints
parameter is optional.
-
Please note that the origin
and destination
within a route can not be empty. You must be supply them with a set of latitude and longitude coordinates signifying a place or a location. Also, when you pass latitude/longitude coordinates of a place, please note that they could be snapped to the coordinates of the nearest road.
Optional parameters
avoid
: Theavoid
parameters are the restrictions adhering to which the best route is be calculated. These restrictions are indicated by use of theavoid
parameters, and an argument to that parameter indicates the restrictions to avoid. The/directions
endpoint supports following avoid parameters:- tolls- indicates that the calculated route should avoid toll roads/bridges.
- highways- indicates that the calculated route should avoid highways.
- ferries- indicates that the calculated route should avoid ferries.
It’s possible to request a route that avoids multiple (or combination of) restrictions of tolls, highways and ferries.
For example, let’s say you want to get the best possible driving route from your home in Strathfield, Sydney to your office in the Sydney CBD. You have to pick up some office supplies from your local store in Ashfield, Sydney. You also want to avoid the ferry ride in the route. In this case, you can send a POST
request by calling the /directions
endpoint with the following payload:
Tip!
You can make a
POST
request by calling /geocode
endpoint to get the latitude and longitude coordinates of Strathfield, Sydney CBD and Ashfield.
{
"requests": [
{
"origin": {
"lat": -33.8724538,
"lng": 151.0938379
},
"destination": {
"lat": -33.8681512,
"lng": 151.2101451
},
"waypoints": [
{
"lat": -33.8894781,
"lng": 151.1274125
}
]
}
],
"avoid": [
"ferry"
]
}
This request returns the following travel distance and duration information:
{
"result": {
"routes": [
[
{
"leg": {
"origin": {
"lat": -33.8724538,
"lng": 151.0938379
},
"destination": {
"lat": -33.8894781,
"lng": 151.1274125
},
"avoid": [
"ferry"
]
},
"travelInfo": {
"duration": {
"durationInSeconds": 468
},
"distance": {
"distanceInMeters": 4409
},
"status": "OK"
}
},
{
"leg": {
"origin": {
"lat": -33.8894781,
"lng": 151.1274125
},
"destination": {
"lat": -33.8681512,
"lng": 151.2101451
},
"avoid": [
"ferry"
]
},
"travelInfo": {
"duration": {
"durationInSeconds": 924
},
"distance": {
"distanceInMeters": 10386
},
"status": "OK"
}
}
]
]
}
}
From the response, you can see that the driving time and distance via the optimal route to travel from Strathfield, Sydney (origin) to Ashfield, Sydney (waypoint) while avoiding the ferry is 468 seconds and 4409 meters respectively. Likewise, the driving time and distance via the optimal route to travel from Ashfield, Sydney (waypoint) to Sydney CBD (destination) is 924 seconds and 10386 meters respectively.
For the schema information of this endpoint, please refer to /directions
.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.