Directions API

Finding 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

  1. requests: The requests 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 the destination 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 the request, the waypoints 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

  1. avoid: The avoid parameters are the restrictions adhering to which the best route is be calculated. These restrictions are indicated by use of the avoid 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:

{
  "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.