Previously, we discussed Google Distance Matrix API in our series of exploring various Google Web Service APIs included in the Google Maps Platform. In this article, we will discuss about Google Directions API called upon when we press ‘Directions’ button on our mobile phones.
What is Google Directions API?
The aptly named Google Directions API is a powerful web service, an integral part of the Google Maps Platform. As the prior discussed “Distance Matrix API” helps in deducing the estimated distance and ETA between various coordinates or places, the major purpose of “Directions API” is to calculate and identify various legal routes connecting the provided waypoints by a user.
The Directions API is a lot more complicated to use and parse than other web services in the Google Maps Platform. It’s because of the large amount of data sent in response, including:
- A large degree of compressed data
- Data in algorithm format
That needs to be decompressed and converted to be readable and displayed to the user.
In this article, we will emphasize on most of the basic properties of the Directions API, and its more useful and commonly used features.
Setup
Google might have made its services public, but obviously, you have to pay for these services. To avail any services from the Google Maps Platform, follow the instructions here: Set up Cloud Console and API Keys. These instructions will help you set up your project on the Google Cloud Console and your API keys for usage and billing purposes.
Google Directions API Format
Google’s Directions API is used to retrieve legal route paths between various coordinates provided to the API as parameters. The Directions API has the following format:
https://maps.googleapis.com/maps/api/directions/json? origin=33.1198628,-117.2827128&destination=32.8270563,-117.3100302&key=XXXXXXXXXXXXXX
Google Directions API Required Parameters
The URL includes a few optional and required parameters needed to get the required result from the API. The below image shows the list of required parameters:
Origins would be the starting points of a journey, and the destinations would be the ending points. You would get the API key from the Google Cloud Console after setting up your project. All parameters would be added after the main URL and followed by the output format, either ‘json’ or ‘xml’.
https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
The parameters would be in a specific format; the name of the parameter followed by a value, separated by an equals sign ‘=’ and different parameters would be separated by an Ampersand sign ‘&’.
origin=33.1198628,-117.2827128&destination=32.8270563,-117.3100302
Google Directions API Optional Parameters
Apart from the required parameters we discussed above, the Distance Matrix API gives us a wide range of optional parameters to add to our request to modify the response we need accordingly. For example, we could add the ‘units’ parameter to specify if we need the value in imperial or metric format. We could also specify the travel mode for which we require our estimated values for, i.e., driving, walking, etc.
units=metric&mode=transit
The following endpoint contains parameters that could be used to estimate the time and distance between two locations for a transit route by bus and which would be optimized to include the least walking.
https://maps.googleapis.com/maps/api/directions/json?units=metric&origin=33.1198628,-117.2827128&destination=32.8270563,-117.3100302&mode=transit&transit_mode=bus&transit_routing_preference=less_walking&key=XXXXXXXXXXXXXX
The next API endpoint would return values for routes between two origin points and two destination points where the travel mode would be driving, with setting the departure time to now, the ‘traffic_model’ parameter set to optimistic. So, the values would be returned considering the best case scenario in terms of traffic and asking the API to choose a path where tolls can be avoided.
https://maps.googleapis.com/maps/api/directions/json? origins=33.1198628,-117.2827128|32.8270563,-117.3100302|&destinations=32.8270563,-117.3100302|33.1198628,-117.2827128|&mode=driving&departure_time=now&traffic_model=optimistic&avoid=tolls&key=XXXXXXXXXXXXXX
If we specify either the ‘departure_time’ parameter or the ‘traffic_model’ parameter, the API will return another value in response inside the ‘elements’ json object with the key ‘duration_in_traffic’. In this case, the value of the field would be the total amount of bustling traffic time the chosen route might entail.
It is important to note that the API would select the best route for individual coordinates, and the values returned would be in accordance with that one single route selected by the API.
For a more in depth overview of the Google Distance Matrix API, visit the official documents here: https://developers.google.com/maps/documentation/directions/overview.
Google Directions API Response
The output result could be in either json or xml format. The following image shows major parts of the output result in json format for a basic GET request.
The most important data is contained inside the “routes” key in the response JSON. Other data keys in the JSON response returned by calling the Directions API include “geocoded_waypoints” and the usual “status” key.
The status key contains a single string to alert the user of whether the API response was successfully retrieved or not. Whereas, the geocoded_waypoints key contains an array with details about the geocoding of origin, destination, and waypoints.
The routes section of the JSON response contains the most relevant and important datasets for displaying and building our routes. Each route consists of various “legs” – the number of legs depends upon the number of waypoints between the origin and destination.
In the case of 0 waypoints, there would be only one leg. Each leg would contain different information about the origin and destination locations, such as their coordinates and addresses (also could be retrieved using the Places API, to be discussed in the future) as well as the distance and duration that we also discussed previously in the Google Distance Matrix API implementation.
An important dataset of each leg is the “overview_polyline” key which contains the string denoted by the key “points”. This field contains a string of single points object that holds an encoded polyline representation of the step. This polyline is an approximate (smoothed) path of the step. Polyline encoding is a lossy compression algorithm that allows you to store a series of coordinates as a single string. This string of encoded characters can be used to visually represent and draw a route on a virtual map such as a Google Map Object or Mapbox widget.
Note: More details on how to convert this encoded polyline into colored lines to depict a route on a map will be discussed in future articles.
Among all the fields contained inside each individual legs, JSON object is the field by the name of “steps”. Like legs, the steps key also contains a list of JSON objects in which the leg is broken down into various smaller routes in the form of steps.
Each step object contains the same fields as the parent leg object, such as the distance, duration, and information about the starting and end location. Each step also displays its own route polyline. The two unique fields include “travel mode,” which as suggested by the name, represents the type of travel against which the API has returned the response for, dependent on the optional parameters, and “HTML instructions.” It contains an html string including some primitive styling used to display a descriptive message to show the user about the current step they might be on. All these important datasets of the Directions API response can be retrieved and parsed to exhibit a meaningful navigational experience for the user.
Conclusion
This article was a continuation of the exploration of helpful Google Maps Platform and their relevant Google Service APIs. As we dig deeper into their implementation, we will delve into more useful APIs. The platform can provide more information on how to implement them in various front-end applications developed in different popular frameworks.
In the future, we will explore more Web Service APIs available in the Google Maps Platform and, by using these, how we can make our own customized version of the Google Maps Experience. See you all then! 
.
