Thursday, October 29, 2009

Directions in the Maps API v3: Where will you go from here?

One of the primary uses of a map has always been to figure out how to get from point A to point B. Until now the only way users of our Maps API v3 could put directions on their map was to draw a straight polyline and tell people to fly. Well, fret no more: we've just released Directions in v3, and rather than just porting it over from v2, we've given it a complete makeover and hope you'll like the new look.

So, what does the new Directions interface look like? We've split the GDirections object from v2 into two separate classes that work together to give you routing goodness. DirectionsService passes directions queries to our server and returns the results in JSON format, while DirectionsRenderer displays the results on your map. The 'load' event from v2 has been removed; instead, a callback function containing your rendering code is passed to the DirectionsService when making a new query.

We've also introduced a couple of options for specifing the kind of results that you want returned from our server. If there's more than one way to get from A to B, you can opt to retrieve all of them with provideTripAlternatives, and if the imperial system offends you, just tell the DirectionsService that you always want metric units returned by using unitSystem. Here's a code snippet that adds directions to a map and step-by-step instructions to an accompanying panel, as well as specifying both of the new options:

 
var map = new google.maps.Map(document.getElementById("map_canvas"), {
  zoom: 7,
  mapTypeId: google.maps.MapTypeId.ROADMAP,
  center: new google.maps.LatLng(-33.868011, 151207566)
});
 
var directionsRenderer = new google.maps.DirectionsRenderer();
directionsRenderer.setMap(map);    
directionsRenderer.setPanel(document.getElementById('directionsPanel'));
 
var directionsService = new google.maps.DirectionsService();
var request = {
  origin: "Sydney, NSW", 
  destination: "Chatswood, NSW",
  travelMode: google.maps.DirectionsTravelMode.DRIVING,
  unitSystem: google.maps.DirectionsUnitSystem.METRIC,
  provideTripAlternatives: true
};
directionsService.route(request, function(response, status) {
  if (status == google.maps.DirectionsStatus.OK) {
    directionsRenderer.setDirections(response);
  } else {
    alert('Error: ' + status);
  }
});

You'll get something that looks like this:

To get started, take a look at the reference and an explanation of the concepts involved, as well as the examples. As always, tell us if you have any questions or comments. We may not choose the most interesting route for you to travel on, but you can rest assured that if you ever want to drive from Seattle to Honolulu, we'll...draw a straight polyline and tell you to kayak*.

Bon voyage!

* because we don't know if your car is watertight.