Using Routes and Directions

You are not viewing the latest version of the AJAX control. Bing Maps AJAX V7 is the recommended JavaScript control for Bing Maps. If you need this documentation, it is available in as a CHM or PDF download.

You can use the Bing Maps routing and driving directions feature to show routes on your custom maps. Routes are automatically drawn on the map, and you can customize the driving directions by writing your own event handler.

Getting a Route

If you want to display a driving route from one point to another on the map, with possible interim points, call the VEMap.GetDirections Method. Any point can be specified as an address, place name, or VELatLong Class object. The following examples are both valid.

var myOptions = new VERouteOptions();
myOptions.SetBestMapView = false; // Don't change map view
myOptions.RouteCallback = myRouteHandler;  // Gets VERoute
map.GetDirections(["space needle", "LA Coliseum", "area 51"], myOptions);
map.GetDirections(["1 Microsoft Way, 98052", new VELatLong(47.969,-122.39, 0, VEAltitudeMode.RelativeToGround)], myOptions);

The route is drawn on the map with start and end icons and waypoint icons. Each of the icons has a default enhanced preview that displays the driving directions for that step. The myRouteHandler function gets a VERoute Class object, which you can use to display the driving directions.

Showing Driving Directions

The VERoute object contains the details about the route, including the driving directions. When calling the GetDirections method, you can specify a callback function to handle the VERoute object and use the information to display driving directions. The following example shows how to display the route information in a JavaScript alert.

function myRouteHandler(route)
{
   // Unroll route and populate alert text
   var legs          = route.RouteLegs;
   var turns         = "Turn-by-Turn Directions\n";
   var leg           = null;
   var turnNum       = 0;  // The turn #
   var totalDistance = 0;  // The sum of all leg distances

   // Get intermediate legs
   for(var i = 0; i < legs.length; i++)
   {
      // Get this leg so we don't have to dereference multiple times
      leg = legs[i];  // Leg is a VERouteLeg object

      // Unroll each intermediate leg
      var turn        = null;  // The itinerary leg
      var legDistance = null;  // The distance for this leg

      for(var j = 0; j < leg.Itinerary.Items.length; j ++)
      {
         turnNum++;
         // turn is a VERouteItineraryItem object
         turn = leg.Itinerary.Items[j];  
         turns += turnNum + ":  " + turn.Text;
         legDistance    = turn.Distance;
         totalDistance += legDistance;

         // Round distances to 1/10ths
         // Note that miles is the default
         turns += " (" + legDistance.toFixed(1) + " miles)\n";
      }
   }
   turns += "Total distance:  " + totalDistance.toFixed(1) + " miles\n";

   // Show directions
   alert(turns);
}

Returning Localized Directions

Information about returning localized directions including how to set the map control culture and a list of supported cultures can be found in the Returning Localized Results topic.

If the localized content should be in kilometers instead of miles, set the VERouteOptions.DistanceUnit Property to VERouteDistanceUnit.Kilometer.

Changing the Defaults

By default, the route is calculated in the order in which the locations are specified, and distances are calculated in miles. However, you can specify the shortest route by distance or quickest route by time and change the units to kilometers by setting the appropriate VERouteOptions Class properties, as follows.

myOptions.RouteOptimize = VERouteOptimize.MinimizeDistance;
myOptions.RouteOptimize = VERouteOptimize.MinimizeTime;
myOptions.DistanceUnit  = VERouteDistanceUnit.Kilometer;