Using Directions

In the previous example we created a simple Route object and used the Route object's GetDirections method to obtain a Directions object for the route. In this example we will use the Directions object to find the distance along a route, estimate the time it will take to travel the route and obtain written driving directions for the route.

GeoBase provides the capability to create written directions. In the following example we will iterate through the set of directions, myDirections, retrieved from our route. Each Direction object in myDirections has a number of properties and methods. We will use the following:

• GetDistance to obtain the distance traveled since the last movement
• IsArrival to determine whether we have reached a stop on the route
• Instructions to obtain a driving instruction (such as "At the end of 'Maple Rd' turn right onto 'Elm Rd'")
• HeadingString to describe the direction of travel (such as "North-East")
• Street to display the name of the new street or road being traveled

/* Keep track of the distance traveled */
double totalDist = 0;

/* Used to build the driving instructions */
StringBuilder instruction = new StringBuilder();

foreach (Direction d in myDirections) {
  instruction.Length = 0;

  /* A note isn't as detailed as a Movement, so just display its instructions */
  if (d is Note) {
      instruction.AppendFormat("Note: {0}.\n\n", d.Instructions);
  }

  if (d is Movement) {
    /* How far have we traveled so far? */
    totalDist += d.GetDistance(DistanceUnit.MILES);

    if (d.IsDeparture) {
        /* it's the start of the journey ... */
          instruction.AppendFormat("Start of journey: {0}.\n\n", d.Instructions);
    }

    if (d.IsArrival) {
        /* it's the end of the journey ... */
        instruction.AppendFormat("End of journey, {0}.\n\n", d.Instructions);
    } 

    /* ... otherwise get instructions, heading and street */
    else {
      instruction.AppendFormat("Total distance {0} miles. {1}", totalDist.ToString("0.0"), d.Instructions);
      instruction.AppendFormat("Now traveling {0} on '{1}'.\n", d.HeadingString, d.Street);
    }
  }

  /* Output the generated instruction */
  Console.WriteLine(instruction);
}

When the directions are generated for the simple route given in the previous section, the output will be similar to the following:

A Directions object is a collection of Direction objects. A Direction object may be one of two types: a Note or a Movement.

• A note never requires action and is purely informative (such as Name changes to Shoreline Hwy [CA-1]).

• A movement requires action and is an essential driving instruction (such as Take first right onto 'Cherry Ave').

Tip
It is possible for a route to be followed using only movement directions.

A Movement object stores the distance between itself and the preceding Movement object, any Note objects in-between are ignored for purposes of distance calculation. To demonstrate this, consider the following route with three Direction objects: two Movement objects (start journey, end journey) and one Note object (road name change).

To find the total length of the route you can use the GetTotalDistance method:

double totalDistance = myDirections.GetTotalDistance(DistanceUnit.MILES);

The Directions object provides the GetTotalTime method to retrieve the estimated total length of the route, as a TimeSpan object.

TimeSpan time = myDirections.GetTotalTime();

Displaying a Route