Section 7.1. Understanding Route APIs

7.1. Understanding Route APIs

The Route Service end point is located at RouteService.asmx, and the APIs available for Route service are exposed via the RouteServiceSoap class in the Web Service proxy (Reference.cs or Reference.vb).

RouteServiceSoap class contains methods related to route functionality, namely CalculateRoute and CalculateSimpleRoute. Either of these two methods can be used to calculate routes between places, addresses, or latitude/longitude coordinates; however, there are some differences that you need to be aware of when using these methods, which we will get to later in this chapter. Table 7-1 shows the methods offered by the RouteServiceSoap class.

Table 7-1. Methods available on the RouteServiceSoap class

Method	Notes
CalculateRoute	Calculates and returns a route (Route object) based on identified route segments and specifications
CalculateSimpleRoute	Calculates and returns a route (Route object) based on an array of latitude and longitude coordinates

Before I get into the details of using the route-related methods, let's look at how a route is represented in MapPoint Web Service APIs.

7.1.1. Anatomy of a Route

In MapPoint Web Service, a route is made up of two or more waypoints, each of which indicates a starting point, ending point, or stopping point along the route. Each waypoint is associated with a route segment, which connects two waypoints but contains information about only one of them. To understand this better, see Figure 7-1.

Figure 7-1. Sample route with segments and waypoints

Figure 7-1 shows with five waypoints and five associated segments. The starting point (waypoint A) and other stopping points (waypoints B, C, and D) in this route are connected via four route segments (1, 2, 3, and 4); the last segment represents the finish point, waypoint E, with its own route segment, 5. In MapPoint Web Service APIs, each segment contains information about the beginning waypoint, the segment distance, and directions for the segment.

Next, let's see how the route in Figure 7-1 morphs into programmatic types.

7.1.2. Representing a Route Programmatically

In MapPoint Web Service APIs, a valid route is always represented by a Route object. A Route object contains the following instances:

• A RouteItinerary class that represents the textual driving directions

• A RouteSpecification class that represents the specifications such as starting point, ending point, stopping points, and driver's profile

• A CalculatedRouteRepresentation class that contains a cached version of the route for rendering purposes

When a route is calculated using RouteServiceSoap.CalculateRoute with an instance of the RouteSpecification class, both RouteItinerary and CalculatedRouteRepresentation are returned by default. However, you can change this behavior and mask the unnecessary information depending on your needs using RouteResultMask enumeration.

A valid RouteItinerary object contains information about the route itinerary and map view representations. The itinerary information is represented as an array of Segment objects. Each Segment object contains a Waypoint object that denotes the starting point for that segment in the route, and an array of Direction objects that indicate driving directions for the current segments. Each Direction object contains detailed textual driving directions, as well as other information such as bearing, latitude/longitude of the directions' starting point, and formatted text instruction. Finally, each Waypoint object contains the location information for the starting point of the corresponding Segment object.

A valid RouteSpecification object defines a route in terms of a segment collection using an array of SegmentSpecification objects in conjunction with a DriverProfile that sets the driving time preferences. Each SegmentSpecification object contains specifications for an individual route segment by setting the waypoint (the starting point for the segment) and other segment preferences indicating what type of segment the current segment needs to besuch as a shortest segment or a quickest segment. Table 7-2 shows the fields exposed on the RouteSpecification class.

Table 7-2. Fields exposed on the RouteSpecification class

Field	Notes
DataSourceName	Name of the data source as a string.
DriverProfile	The time to start and end driving each day (DriverProfile object).
ResultMask	Indicates, as a RouteResultMask enumeration, whether a returned route should include driving directions, a calculated route representation, or both.
Segments	The specification of each segment that makes up the route as an array of SegmentSpecification objects. The order of the array is the order of the stops on the route.

Table 7-3 shows the fields of the SegmentSpecification object:

Table 7-3. SegmentSpecification fields

Field	Notes
Options	The route preference and map view options (SegmentOptions object) for the specified segment of the route
Waypoint	The waypoint (Waypoint object) for the route segment; the beginning of the segment

When you are calculating a route, a RouteSpecification object is passed to the RouteServiceSoap.CalculateRoute, and the resulting Route object automatically inherits these route specifications as an instance of the RouteSpecification object, so you never actually assign a RouteSpecification instance to a Route object.

Finally, the CalculatedRouteRepresentation object is a cached representation of a calculated route; this object is useful only in rendering a route on top of a map, so a valid instance of this object contains an array of bytes that represents the calculated route, which can later be used in rendering a map using the MapPoint Web Service route service.

This discussion is summarized in Figure 7-2.

Figure 7-2. Programmatic representation of a route using MapPoint Web Service types

With this introduction, let's look at how to create Route objects using the RouteServiceSoap APIs.