Calculating a Route

You can specify a route with the calculateRoute operation. The start, destination, and optional via points can be either specified with an address or a map coordinate. In the former case the given addresses will be geocoded with the Map24 Geocoder. Only if the geocoding is successful, the Map24 Routing Service will calculate the route.

The result of the calculateRoute operation always contains the geometry of the route and a route ID. The route ID can be used to identify the calculated route on the server in subsequest requests. If specified in the request, the result also contains a detailed route description. The language of the description can be defined in the request.

The following listing shows the general structure of the operation in the WSDL file of the Map24 Routing Service:

...  
<message name="calculateRouteRequest" >
<part name="RequestHeader" type="tns:RequestHeader" />
<part name="CalculateRouteRequest" type="tns:CalculateRouteRequest" />
</message>
<message name="calculateRouteResponse" >
<part name="CalculateRouteResponse" type="tns:CalculateRouteResponse" />
</message>
...
<portType name="Map24RoutingPortType" >
<operation name="calculateRoute" >
<input message="tns:calculateRouteRequest" />
<output message="tns:calculateRouteResponse" />
</operation>
...
</portType>
...

Request

You can set the parameters for the calculateRoute operation in a CalculateRouteRequest element.

CalculateRouteRequest provides several fields to specify the start, destination, and via points, to fine tune the routing algorithm and to specify which information should be provided in the response:

Field	Description
MaxNoOfGeocodeAlternatives	The maximum number of returned geocoding results for the given address.
CalculationMode	The mode for the route calculation. This may be either "shortest" or "fastest" and is "fastest" by default. Be aware that the shortest route must not necessarily be the fastest.
VehicleType	Type of the vehicle with which the route is traversed. The value can be either "Car" or "Pedestrian". It is "Car" by default. In case of "Pedestrian" motorways are not used. Furthermore, one-way rules and other direction instructions are ignored in this case.
SpeedClassification	An optional field of type SpeedClassification for specifying the assumed average speed on different road types. This field can be used to change the default values. Note: The SpeedClassification settings can influence the calculation of the time for traversing the route (TotalTime field in the route description), but they do not have any effect on the course of the route.
IgnoreWaypoints	The coordinates that describe the geometry of the route are called way points. If this field is set to FALSE (the default), all way points of the route are returned in the response. When setting this field to TRUE, only one coordinate per route segment is returned. This option can for example be used to center on a route segment or to show a logo for each route segment. Note that it is not necessary to set this flag to FALSE for showing the route on the map, since the coordinates for showing the route are received from the server.
IgnoreDescription	If TRUE, only the RouteID is returned. If FALSE (the default), the RouteID and a detailed route description is returned. The RouteID is needed to identify the route information on the server in subsequent requests.
DescriptionLanguage	The language for the textual route description. Use the two-letter language code as specified in ISO 639-1. The following languages are supported: Czech (cs), German (de), Danish (da), English (en), Spanish (es), Finnish (fi), French (fr), Croatian (hr), Hungarian (hu), Icelandic (is), Italian (it), Dutch (nl), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Swedish (sv), Turkish (tr). If no DescriptionLanguage is specified, the language associated with the Map24 ID in the RequestHeader will be used. Note: The measuring unit used in route descriptions depends on the DescriptionLanguage setting. For most of the supported languages this is kilometers, also for "en" (English). It is possible to change the measuring unit in the route description to miles and yards by setting the DescriptionLanguage field to "en_gb" (British English) or "us" (American English).
Start	The start point of the route. Alternatively, it is possible to define a Map24 Location as start of the route in the StartLocationID field.
Destination	The destination point of the route. Alternatively, it is possible to define a Map24 Location as destination of the route in the DestinationLocationID field.
StartLocationID	ID of a Map24 Location used as start of a route. Instead of passing a coordinate in the Start field it is possible to pass the ID of a Map24 Location as start point of a route. Note: This functionality is only available for custom locations that are uploaded and stored in the Map24 Database via XML sync.
DestinationLocationID	ID of a Map24 Location used as destination of a route. Instead of passing a coordinate in the Destination field it is possible to pass the ID of a Map24 Location as destination of a route. Note: This functionality is only available for custom locations that are uploaded and stored in the Map24 Database via XML sync.
ReturnDistanceSummaries	If true, the Map24 Routing Service returns the distances to be traversed on different road types such as highways, country roads, etc. The distance summaries are given for each traversed country. In addition, it is distinguished between distances traversed inside and outside buildup areas.
Vias	Deprecated.
ViaPoints	The via points used to define the course of the route.
LoadTMCs	If you have a license from the NAVTEQ GmbH for retrieving traffic information, you can receive traffic information along the calculated route by setting the LoadTMCs flag to TRUE.
RoutingServiceID	Optional parameter that can be used for specifying to which Map24 Routing Service instance the request is sent.
MinQualityOfGeocodeResults	If you have specified the start, destination, and via points with an address, the Map24 Geocoder will geocode these addresses. With the MinQualityOfGeocodeResults field you can specify the quality that the geocoded addresses should have at least. The default value is 40% which means that the street contained in the geocoded address must match the street that was provided in the request. Otherwise, the route is not calculated.
TruckAttributes	Since service_version=20081229 it is possible to take truck attributes such as height, length, and weight of the vehicle into account for route calculation.
MayUseHovLanes	Since service_version=20081229 the user can specify whether to take HOV (high occupancy vehicle) lanes into account for the route computation or not. This is a Boolean field specifying whether to use HOV lanes (MayUseHovLanes=true) or not (MayUseHovLanes=false).
Properties	Additional parameters (key-value pairs) for fine tuning the routing algorithm and for defining what should be returned in the route description. Detailed information is available here.

Response

CalculateRouteResponse contains the result of the calculateRoute operation.

Field	Description
ResponseHeader	Returns the same information that was provided in the RequestHeader.
StartAddress	The geocoded start address of type GeocodedAddress.
DestinationAddress	The geocoded destination address of type GeocodedAddress
ViaAddresses	An array containing the geocoded via addresses of type GeocodedAddress.
Route	The calculated route of type Route.

Examples

CalculateRoute Request with a Via Point

CalculateRoute Request with a Via Point "TRANSIT"

CalculateRoute Request that Returns Distance Summaries