The Bing Maps team has added a new feature to the Bing Maps REST Services Routes API called “via” waypoints. This feature already exists on the Bing Maps consumer site (http://www.bing.com/maps ) as the ability to drag-and-drop a route to create one or more “via” waypoints. We are excited to expose it to developers using the Bing Maps REST Services API.
The first question that might come to mind is “If there is a new “via” waypoint, then how is that different from a “waypoint”?” For the sake of discussion, let’s call our beloved old waypoint a “stop” waypoint.
First, a little bit of context. In the “old world”, the Routes API only supported “stop” waypoints, and a Routes API request could have two or more “stop" waypoints. In the simplest scenario, two waypoints specify the start and the end locations of the route, and the result is a route leg between these two locations with an itinerary (i.e., set of driving instructions). Adding additional “stop” waypoints adds additional route legs, each with its own itinerary. It is important for a route leg to have its own itinerary because every itinerary includes a “depart” and an “arrive” instruction. The only thing these adjacent route legs have in common is a shared waypoint because each route leg is calculated independently.. This scenario is still supported in the “new world”. The image below shows this scenario with three (3) waypoints.
Note that in this example, [A], [B] and [C] are all stop waypoints. [A-B] and [B-C] represent two different legs that both have their own itinerary and, most importantly, [B-C] is calculated with no assumptions about [A-B].The only thing the legs have in common is a shared waypoint. If you look carefully, you will see that there is an implicit U-turn between legs that is not mentioned in the written instructions. The REST Services URL for this Routes API request looks like this:
http://dev.virtualearth.net/REST/V1/Routes?wp.1=47.617540,-122.353513&wp.2=47.616669,-122.351845&wp.3=47.617410,-122.351909&output=xml&key=[BingMapsKey]
Now, let’s look how “via” waypoints enhance this route.
“Via” waypoints are still waypoints (i.e., they represent a location), but “via” waypoints are used to define intermediate locations between “stop” waypoints. In the “new world”, route legs can contain “via” waypoints that the route must pass through. Going back to our example above, if we change [B] to “via” waypoint (as indicated by the small green point on the map below), the route result changes significantly: (1) There is only one route leg now, and (2) The [B-C] route leg is calculated based on the direction that we are going when we arrive at [B] from [A].
The REST Services URL for this Routes API request looks like this:
http://dev.virtualearth.net/REST/V1/Routes?wp.1=47.617540,-122.353513&vwp.2=47.616669,-122.351845&wp.3=47.617410,-122.351909&output=xml&key=[BingMapsKey]
Note that the only difference is that the second waypoint is specified as a “via” waypoint with the alias “vwp”.
With this new feature, developers can define a maximum of 10 “via” waypoints between each set of “stop” waypoints. “Via” waypoints can support a rich set of scenarios ranging from simple ones like specifying preferred routes, to more sophisticated ones like responding to new route points created by drag-and-drop operations. For details about this new feature, please refer to the Bing Maps REST Routes API reference.
Have fun!
Engin Uzuncaova
Software Design Engineer - Bing Maps Directions Team