VEMap.GetDirections Method

  • Article

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.

Draws a multi-point route on the map and sends details about the route to a callback function.

VEMap.GetDirections(locations, options);

Parameters

Parameter Description

locations

An array of objects specifying the points through which the route must pass. The points can be either VELatLong Class objects or String objects. A maximum of 25 locations can be specified.

options

A VERouteOptions Class object specifying the routing options.

Return Value

The callback function specified in the VERouteOptions.RouteCallback Property of the VERouteOptions object passed to the options parameter receives a VERoute Class object containing route details, including the step-by-step route directions.

If the locations parameter length is greater than 25, an empty VERoute object will be returned. An empty VERoute object has no itinerary and the VERoute.Distance Property and VERoute.Time Property are 0.

If one or more of the points specified in the locations parameter is not found, then will be returned to the callback function.

If the VERouteOptions.RouteMode Property is set to VERouteMode.Walking, an empty VERoute object will be returned if the total route distance between the start and end points is greater than 16 kilometers. This total route distance includes portions of the route where you may not be walking. For example, ferry segments of the route are included in the total route distance.

Remarks

The route can contain localized directions by adding a mkt attribute to the map control reference. Information about returning localized results including supported cultures can be found in the Returning Localized Results topic.

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

If the VERouteOptions.RouteMode Property is set to VERouteMode.Walking, a walking speed of 4.8 km/hr is used to calculate the route time.

Example

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
   <head>
      <title></title>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

      <script type="text/javascript" src="https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3"></script>

      <script type="text/javascript">
         var map = null;

         // Initial map view
         var SeattleEastside = new VELatLong(47.65, -122.24, 0, VEAltitudeMode.Default);

         function GetMap()
         {
            map = new VEMap('myMap');
            map.LoadMap(SeattleEastside, 8);
         }

         function GetRouteMap()
         {
            var locations;

            if (legForm.legType[0].checked)
            {
          locations = new Array("Tacoma WA", "Seattle WA", "Everett WA");
            }
            else if (legForm.legType[1].checked)
            {
               locations = new Array("Tacoma WA", "Bellevue WA", "Everett WA");
            }

            var options = new VERouteOptions;

            // Otherwise what's the point?
            options.DrawRoute      = true;

            // So the map doesn't change:
            options.SetBestMapView = false;

            // Call this function when map route is determined:
            options.RouteCallback  = ShowTurns;

            // Show as miles
            options.DistanceUnit   = VERouteDistanceUnit.Mile;

            // Show the disambiguation dialog
            options.ShowDisambiguation = true;

            map.GetDirections(locations, options);
         }

         function ShowTurns(route)
         {
            var turns = "<h3>Turn-by-Turn Directions</h3>(rounding errors are possible)";

            turns += "<p><b>Distance:</b> " + route.Distance.toFixed(1) + " miles";

            turns += "<br/><b>Time:</b> " + GetTime(route.Time) + "</p>";

            if (dirsForm.dirsType[0].checked)
            {
               // Unroll route and populate DIV
               var legs          = route.RouteLegs;
               var leg           = null;
               var turnNum       = 0;  // The turn #

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

                  var legNum = i + 1;
                  turns += "<br/><b>Distance for leg " + legNum + ":</b> " + leg.Distance.toFixed(1) + " miles" +
                           "<br/><b>Time for leg "     + legNum + ":</b> " + GetTime(leg.Time) + "<br/><br/>";

                  // 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 = leg.Itinerary.Items[j];  // turn is a VERouteItineraryItem object

                     turns += "<b>" + turnNum + "</b>\t" + turn.Text;

                     legDistance    = turn.Distance;

                     // So we don't show 0.0 for the arrival
                     if(legDistance > 0)
                     {
                        // Round distances to 1/10ths
                        turns += " (" + legDistance.toFixed(1) + " miles";

                        // Append time if found
                        if(turn.Time != null)
                        {
                           turns += "; " + GetTime(turn.Time);
                        }

                        turns += ")<br/>";
                     }
                  }

                  turns += "<br/>";
               }

               // Populate DIV with directions
               SetDirections(turns);
            }
         }

         function SetDirections(s)
         {
            var d = document.getElementById("directions");
            d.innerHTML = s;
         }

         // time is an integer representing seconds
         // returns a formatted string
         function GetTime(time)
         {
            if(time == null)
            {
               return("");
            }

            if(time > 60)
            {                                 // if time == 100
               var seconds = time % 60;       // seconds == 40
               var minutes = time - seconds;  // minutes == 60
               minutes     = minutes / 60;    // minutes == 1


               if(minutes > 60)
               {                                     // if minutes == 100
                  var minLeft = minutes % 60;        // minLeft    == 40
                  var hours   = minutes - minLeft;   // hours      == 60
                  hours       = hours / 60;          // hours      == 1

                  return(hours + " hour(s), " + minLeft + " minute(s), " + seconds + " second(s)");
               }
               else
               {
                  return(minutes + " minutes, " + seconds + " seconds");
               }
            }
            else
            {
               return(time + " seconds");
            }
         }
        
         function ClearAll()
         {
            map.DeleteRoute();
            SetDirections("");
            map.LoadMap(SeattleEastside, 8);
         }
      </script>
   </head>
   <body onload="GetMap();" style="font-family:Arial">
      <h3>Get a Route and Directions (optional) from Tacoma to Everett</h3>

      <div id='myMap' style="position:relative; width:400px; height:400px;"></div>

      <form name="legForm">
         Route:
         <br/>
         <input id="thruSeattle" type="radio" name="legType" checked="checked"/>
        Through Seattle
         <br/>
         <input id="thruBellevue" type="radio" name="legType"/>
        Through Bellevue
      </form>

      <form name="dirsForm">
         <input id="showdirs" type="radio" name="dirsType" checked="checked"/>
         Show turn-by-turn directions (below)
         <br/>
         <input id="showdirs" type="radio" name="dirsType"/>
         Don't show turn-by-turn directions
      </form>

      <input id="getroutemap" type="button" value="Get Route Map" onclick="GetRouteMap();"/>
      <input id="clear"       type="button" value="Clear All"     onclick="ClearAll();"/>

      <div id='directions'></div>
   </body>
</html>

See Also

Concepts

VERouteOptions Class
VERoute Class
Returning Localized Results