Using the Google Directions API

Overview

The Google GeoCode API offers a service for retrieving driving directions between 2 addresses.

Syntax

The service is exposed through a URI. The syntax of the URI is

http://maps.googleapis.com/maps/api/directions/output?parameters

output is the format in which I want to receive result – either “json” or “xml”. I prefer the simplicity of json.

parameters is an ampersand-delimited list of name value pairs to pass to the API. The parameters I care about are

Origin	The starting address
destination	The ending address
alternatives	”true”, if you want the service to return more than one possible route. Unless I have a reason to provide multiple routes, I prefer “false”
Units	”imperial” to return data in feet and miles; “metric” to return data in meters and kilometers. This should depend on the country where the data is going to be used.
Sensor	”true”, if I am using a sensor to provide location; otherwise “true”. I don’t own such a sensor, so I set this to false.

Sample Code

Here is a sample URI to request directions from my old office to my new one, returned as JSON data.

http://maps.googleapis.com/maps/api/directions/json?origin=31555 W 14 Mile Road, Farmington Hills, MI, 48334&alternatives=false&units=imperial&destination=26957 Northwestern Highway, Southfield, MI, 48076&sensor=false

This is a nice function to call from JavaScript. I prefer the simple jQuery syntax for making Ajax calls like this.

var startAddress='439 East 31st Street #214, Chicago, IL 60616';

var endAddress='30 North LaSalle St, Chicago, IL 60616’;

var requestUrl = 'http://maps.googleapis.com/maps/api/directions/json?origin=' + startAddress + '&alternatives=false&units=imperial&destination=' + endAddress + '&sensor=false';

$.ajax({ 
url: requestUrl, 
dataType: "json", 
type: "GET", 
data: {}, 
error: function (err) { 
$(#distanceDiv).html("Error calling Web Svc.
Calculate."); 
}, 
success: function (data) { 
var distance = data["routes"][0]["legs"][0]["distance"].text; 
$(# distanceDiv).text(distance); 
} 
});

The code above calls the service; then parses the resulting JSON to retrieve the distance and displays that distance in a DIV with the ID distantDiv. In this example, I hard-coded the 2 addresses, but you could use jQuery selectors to retrieve the address from elements on the page or user input.

Response

Below is part of the Json response to the service call

Limitations

There are some limitations you should be aware of. I am a cheapskate, so I’m using the free version of this API. With the free version, I can only send 2500 addresses per day. If I try to send more, the service will respond with a status of “REQUEST_DENIED” and no results will be returned.

Also, Google expects you to display the results on a Google Map. I’m not sure how they enforce this, but they don’t allow you to use the Geocoding API to display data on someone else’s map.