Short description


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:

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:

Good to know


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