Driving Directions in MapPoint Web Service

I've seen a few implementations of MWS routing (driving directions) used by our customers that aren't necessarily done correctly and it's actually creating some consternation with customer's end users. With that I give you, how to use MWS Driving Directions in your applications.

First some explanations. Routing in MWS consists of both segments and directions.

Segments - A segment is the route associate with each point. For example, if you're going from point A and point B you will have 2 segments. "What?" Yes, the way MWS was written, there is a segment for each point in the route. Thus, driving between points A and B will have 2 segments. Segment also has properties for duration and distance which are relative to the segment so you may need to add them up if you have multiple points along your route. Remember, MWS supports the ability to route up to 50 points - an origin, a destination and 48 stops along the way.

Directions - A direction in MWS routing is the actual direction for turn by turn routing. A direction consists of several properties such as (1) "instruction" which is the actual text of where to turn (for example, "Turn left on Main St."); (2) "distance" which is the distance between the previous maneuver and the next maneuver; (3) "duration" which is the time between the previous maneuver and the next maneuver. These are the most commonly used properties, but the direction attribute also consists of Action, BearingIntoTurn, BearingOutOfTurn, DirectionType, FormattedInstruction, ID, LatLon; Towards, and View. Here's a link to the specific SDK page if you want more information on these specific attributes.

With this in mind, many people have have assumed the there is only 1 segment between two points, so their routes are being truncated and end users are being left in the middle of a freeway with nowhere to turn! The answer is pretty simple and that's a nested loop. What I'm doing below is (1) looping through the segments, so irregardless of the amount of segments that are returned from the service I get them all; (2) looping through the directions, so for every maneuver of every segment I get all of the directions; and (3) displaying the distance, the time and the instruction between each maneuver into a table. (4) I'm also converting the returned distance and duration to a more suitable format (since a double distance rounded to the nearest billionth and the long duration returned in seconds aren't very useful for people).

//C#, of course. :)

for(int x = 0; x < myRoute.Itinerary.Segments.Length; x++)
{
  for(int y = 0; y < myRoute.Itinerary.Segments[x].Directions.Length; y++)
  {
  TableRow tRow = new TableRow();
  TableCell tCell1 = new TableCell();
  tCell1.Text = Convert.ToString(Math.Round(myRoute.Itinerary.Segments[x].Directions[y].Distance * 100)/100);
  tRow.Cells.Add(tCell1);
  TableCell tCell2 = new TableCell();
  tCell2.Text = myRoute.Itinerary.Segments[x].Directions[y].Instruction.ToString();
  tRow.Cells.Add(tCell2);
  TableCell tCell3 = new TableCell();
  if(myRoute.Itinerary.Segments[x].Directions[y].Duration > 60)
  {
    tCell3.Text = Convert.ToString(myRoute.Itinerary.Segments[x].Directions[y].Duration / 60) + " min";
  }
  else
  {
    tCell3.Text = Convert.ToString(myRoute.Itinerary.Segments[x].Directions[y].Duration) + " sec";
  }
  tCell3.Wrap = false;
  tRow.Cells.Add(tCell3);
  Table1.Rows.Add(tRow);
  }
}

With that said, hopefully I won't get dropped off in the middle of the freeway when I'm driving to find the nearest . . . whatever.