Toll

This Technical Concept is relevant to the following Services: xRoute, xDima.

Characteristic

Short description

With the toll related parts of the xRoute API it is possible to retrieve toll costs for a specific routeA route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. and vehicleThe term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability. Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition.. The structure of the response is designed for flexibility and the possibility to tailor the toll report to your needs. Also with xDima the toll costs can optionally be calculated, stored and accessed for each relation of a matrix.

Use

A basic toll summary can be retrieved for a route by setting enabled to true in the toll result fields. With the further result fields sections and systems a detailed toll report can be requested.

In xDima, when a distance matrix is created, the toll costs have to be activated as additional contents in the distance matrix options. In order to get the toll costs of a matrix the corresponding result field has to be activated.

Detailed Consideration

With the toll related parts of the xRoute and xDima API it is possible to retrieve toll costs for a specific route or relation of a matrix, depending also on the vehicle parameters and the reference time.

The xRoute toll report

The toll report in the route response consists of three main parts:

The toll summary contains the total toll costs for the route.
An entry in the list of toll sections represents one single section on the route for which toll has to be paid and provides further information such as payment methods, in which country the cost has to be paid, etc. Please refer to the showcase to see how this information can be aggregated and displayed.
For each toll system where toll has to be paid there will be an entry in this list. It contains basic information about the operator of this toll system and which tariff version was used.

At the leg result there is only the toll summary for each route legA route leg is a part of a route between two consecutive waypoints. which can be retrieved through setting the leg result field toll summary to true. The toll sections of a leg can be determined by two indices into the sections array which are returned as soon as the sections toll result field is set to true. Also the toll events are linked to the toll sections array with a section index.

The xDima toll calculation

In xDima, the toll costs calculation can be requested by setting the option persistTollCosts in the distance matrix options to true. To query the toll costs, the toll result field in the distance matrix contents result fields should be used.

Please note that when using a Create and Get distance matrix request, the option persistTollCosts is ignored and instead the toll costs result field should be used. The time consideration scenarios multiple travel times and exact are not supported when requesting toll prices in xDima.

Time dependency

The toll calculation also considers time dependent toll prices such as different prices for peak hours. It is also possible to calculate toll prices for dates in the future as far as this data is available and contained in the map. Please refer to the technical concept on time consideration which time consideration modes are supported.

Avoiding toll roads during route selection

With setting the toll penalty it is possible to avoid toll roads during route selection. Please note that the toll road sections cannot be avoided if waypointsA waypoint is a geographic location used to specify start, destination and possible stopovers for a route. are put on a toll road.

Vehicle parametrization

In the documentation for the vehicle profile there are sets of numbers at each parameter describing for which features and feature layers they might be used. The number (2) is for toll calculation.

Furthermore, some vehicle parameters can be set through the generic mechanism in the feature layer profile. Sometimes new vehicle parameters are introduced first by this generic mechanism and are later added to the vehicle profileA profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle. with the next API version. Of course it is also possible to adapt these parameters to your needs:

Get the list of parameters relevant for toll calculation: Refer to the integration sample on how to retrieve the available metainformation in the map or check the following list:
- featureLayerProfile/parameters[@key='isCommercial']/@value: Toll operators may assign different prices to vehicles by their legal status. Accepted values are NONE, FALSE and TRUE.
- featureLayerProfile/parameters[@key='numberOfTires']/@value: Toll operators may assign different prices to vehicles if they have twin wheels. We use the combination of number of axles and number of tires to infer this information. If you set more than twice the number of axles, it is considered a twin wheel vehicle.
- featureLayerProfile/parameters[@key='numberOfTractorAxles']/@value: The number of axles for the whole vehicle do not always suffice to represent the vehicle definitions by the toll operators.
- featureLayerProfile/parameters[@key='numberOfTrailerAxles']/@value: The number of axles for the whole vehicle do not always suffice to represent the vehicle definitions by the toll operators.
- featureLayerProfile/parameters[@key='totalPermittedNumberOfPassengers']/@value: Used to distinguish buses from other vehicles.
Adapt your profile: refer to the integration sample on vehicle parametrization.

Good to know

Licensing

The license key toll needs to be activated to render toll roads and to calculate toll prices. Avoidance of toll roads is possible with the general xroute license.

Data formats and sources

As of xServer release 2.9 xRoute supports two different data formats regarding toll:

For the legacy format the xServer provides basic support. A toll summary can be returned for the complete route as well as the legs. Furthermore, it is possible to avoid toll roads. However, it is not possible to get details like the toll sections, toll systems, and toll events along the route. The format won't be further developed and integrated.
With the new format the full detailed toll API is supported, which is stable as of xServer release 2.16. It is in parts still under development.

As switching the production process takes time, upcoming maps may still contain only the legacy format for some or all countries. If there is data in the new format for some country of a continent, by default only the new data format is used for the whole continent. The usage of the legacy format can be enforced by setting the parameter use detailed toll to false.

Showcase	Calculate Toll Costs
Showcase	Calculate Toll Costs with xDima and xRoute
Showcase	Consider Route Events
Integration sample	Displaying toll roads
Integration Sample	Calculating Toll for a Route
Integration Sample	How to Retrieve the Available Metainformation in the Map
Technical Concept	Time Consideration
Technical Concept	Distance Matrices
Technical Concept	High Performance Routing