Calculate Route

A latitude–longitude pair (in EPSG:4326 projection) with the following constraints:

• Latitude values must be in the range [-90, +90].

• Longitude values must be in the range [-180, +180].

Example: 52.37245,4.89406

A location represented as a JSON object. The object should contain two fields: latitude and longitude, each containing a number. Both values must use the same reference frame and follow the same constraints as the location type. Example: {“latitude”: 52.37245, “longitude”: 4.89406}

A circle with a center point and a radius (in meters). The radius must be a positive integer, with a maximum value of 135000.
Note: If entryPoints are provided to the routeStop, the radius is ignored.
Example: circle(52.37245,4.89406,10000)

A location or a circle.
Examples:

• 52.37245,4.89406
• circle(52.37245,4.89406,10000)

A comma-separated list of floats.
Example: 1.23,0

A date and time specified in RFC 3339 format with an optional time zone offset.
Examples:

• 2023-12-19T16:39:57
• 2023-12-19T16:39:57-08:00

A comma-separated speedInkmh,consumptionInLitersPerHundredkm pair. Constraint: speedInkmh must be in the range [0.0, 255.0].
Example: 15.5,10.0

A comma-separated speedInkmh,consumptionInkWhPerHundredkm pair. Constraint: speedInkmh must be in the range [0.0, 255.0].
Example: 15.5,8.0

Avoids toll roads.

Avoids motorways.

Note: Avoiding motorways for long routes of approximately 500km+ may result in computation timeouts of the primary route or path alternatives.

Avoids ferries.

Avoids unpaved roads.

Avoids routes that require use of carpool (HOV/High Occupancy Vehicle) lanes.

Avoids using the same road multiple times.
Most useful in conjunction with routeType=thrilling.

Avoids crossing country borders.

Avoids tunnels.

Avoids car trains.

Avoids low-emission zones.

Requests that the response be compressed.
Value: gzip

Specifies the compression used for the request body. Currently, only gzip is supported. If not specified, no compression is assumed. This is equal to specifying identity.

Values:

• identity
• gzip

Specifies the MIME type of the body of the request.

Value: application/json

Specifies an identifier for the request.

• The value should be unique for each request.

• The value must match the regular expression ’^[a-zA-Z0-9-_\.]{1,100}$’.

• If specified, the same value is sent back in the similar-named response header. Otherwise, a generated value may be sent back.

The base URL used to call the API.
Values:

• api.tomtom.com: The default global API endpoint.

• kr-api.tomtom.com: The region-specific endpoint for South Korea. See the Region-specific content documentation.

The service version number.
Value: The current value is 1.

Locations through which the route is calculated. The following constraints apply:

• At least two locations must be provided.

• The first location in the sequence defines the origin and must be a location.

• The last location in the sequence defines the destination and must be a location.

• One or more optional intermediate generalizedLocations (known as waypoints in this context) may be provided:

  • The maximum allowed number of waypoints is 150.

  • A waypoint of type location results in an extra leg in the response whereas a waypoint of type circle does not.

  • Waypoints of type circle cannot be used when computeBestOrder is true.

Values: Colon-delimited generalizedLocations that follow the constraints mentioned above.

The content type of the response structure.
Possible values:

• json
• jsonp

Note: If the content type is jsonp, a callback method can be specified in the query parameters.

The API key used to authorize requests to the Routing API.
Value: Your valid API Key.

Specifies the jsonp callback method. Only used when contentType is jsonp.
Default value: callback

Specifies which data to report for diagnostic purposes. Possible value is: effectiveSettings.

• Reports the effective parameters or data used when calling the API.

• For defaulted parameters, the returned value reflects the default if the parameter was not specified.

Default value: effectiveSettings

The date and time of departure from the origin point.

• Departure times other than now must be specified as a dateTime.

• If no time zone offset is provided, the origin point’s time zone is assumed.

• The departAt parameter cannot be used in conjunction with arriveAt.

Default value: now
Other value: dateTime

The date and time of arrival at the destination point.

• It must be specified as a dateTime.

• If no time zone offset is provided, the destination point’s time zone is assumed.

The arriveAt parameter cannot be used in conjunction with:

• departAt
• minDeviationDistance
• minDeviationTime
• supportingPointIndexOfOrigin

Value: dateTime

Specifies the type of optimization used when calculating routes.
Possible values:

• fastest: Route calculation is optimized for travel time while keeping routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that save very little time.

• shortest: Route calculation is optimized for travel distance while keeping the routes sensible. For example, straight routes are preferred over those with many turns.

  • Use shortest only for short to medium-distance routes. It explores a much larger search space than fastest, so on long-distance routes — especially when combined with waypoints or avoid options — it can exceed the server’s compute time limit and the request will fail with a timeout. For long-distance planning, use fastest instead. See the FAQ entry How can I reduce the response time? for the full list of parameters that increase compute time.

• short: Route calculation aims to strike a good balance between shorter travel time and shorter travel distance.

• eco: Route calculation aims to strike a good balance between shorter travel time and lower fuel or energy consumption.

• thrilling: Route calculation is optimized to include interesting or challenging roads and to use as few motorways as possible.

  • You can configure the level of turns and the degree of hilliness.

  • Use the hilliness and windingness parameters to set this.

  • There is a limit of 900 km on routes planned with routeType=thrilling.

Default value: fastest

Possible values are:

• true: Use all available traffic information during routing.

• false: Ignore current traffic data during routing. Note that although the current traffic data is ignored during routing, the effect of historic traffic on effective road speeds is still incorporated.

Depending on availability, the Routing API takes road closures and road works into account up to 60 days in the future.
Default value: true

Specifies something that the route calculation should try to avoid when determining the route. The avoid parameter can be specified multiple times (e.g., …&avoid=motorways&avoid=ferries&…).
Possible values are listed under Avoid parameter possible values.

The mode of travel for the requested route.

• Note that the requested travelMode may not be available for the entire route.

• If the requested travelMode is not available for a particular section, the travelMode field for that section in the response will be set to “other”.

Note that travel modes bus, motorcycle, taxi, and van are in BETA functionality.

• Full restriction data is not available in all areas.

Default value: car
Other values:

• truck
• taxi
• bus
• van
• motorcycle
• bicycle
• pedestrian

Degree of hilliness for a thrilling route.
Note: This parameter can only be used in conjunction with routeType=thrilling.
Default value: normal
Other values:

• low
• high

Level of turns for a thrilling route.
Note: This parameter can only be used in conjunction with routeType=thrilling.
Default value: normal
Other values:

• low
• high

Maximum speed of the vehicle in kilometers/hour.

• Must have a value in the range [0, 250].

• A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning.

Default value: 0

Weight of the vehicle in kilograms.

• If a detailed Consumption model is specified, refer to the following Consumption model parameters section for the documentation of vehicleWeight.

• If a detailed Consumption model is not specified, and the value of vehicleWeight is non-zero, then weight restrictions are considered.

• In all other cases, this parameter is ignored.

Default value: 0

Weight per axle of the vehicle in kilograms. A value of 0 means that weight restrictions per axle are not considered.
Default value: 0

Number of axles of the vehicle. A value of 0 means that the number of axles restrictions is not considered.
Default value: 0

Length of the vehicle in meters, including the length of any additional equipment, e.g., trailers, bike racks, etc. A value of 0 means that length restrictions are not considered. Fractional digits are rounded to the closest centimeter while rounding up on a tie.
Default value: 0

Width of the vehicle in meters. A value of 0 means that width restrictions are not considered. Fractional digits are rounded to the closest centimeter while rounding up on a tie.
Default value: 0

Height of the vehicle in meters. A value of 0 means that height restrictions are not considered. Fractional digits are rounded to the closest centimeter while rounding up on a tie.
Default value: 0

Vehicle is used for commercial purposes and thus may not be allowed to drive on some roads.
Default value: false

Specifies types of cargo that may be classified as hazardous materials and are restricted from some roads. The vehicleLoadType parameter can be specified multiple times (e.g.,

or

).
Available values are:

• US Hazmat classes 1 through 9
• Generic classifications for use in other countries.

Use these values for routing in the USA:

• USHazmatClass1: Explosives

• USHazmatClass2: Compressed gas

• USHazmatClass3: Flammable liquids

• USHazmatClass4: Flammable solids

• USHazmatClass5: Oxidizers

• USHazmatClass6: Poisons

• USHazmatClass7: Radioactive

• USHazmatClass8: Corrosives

• USHazmatClass9: Miscellaneous

Use these values for routing in all other countries:

• otherHazmatExplosive: Explosives

• otherHazmatGeneral: Miscellaneous

• otherHazmatHarmfulToWater: Harmful to water

Notes:

• If travelMode is pedestrian or bicycle,vehicleLoadType is not considered.

• The vehicleLoadType and vehicleAdrTunnelRestrictionCode parameters are independent; please provide both if applicable.

If vehicleAdrTunnelRestrictionCode is specified, the vehicle is subject to ADR tunnel restrictions.

• Vehicles with code B are restricted from roads with ADR tunnel categories B, C, D, and E.

• Vehicles with code C are restricted from roads with ADR tunnel categories C, D, and E.

• Vehicles with code D are restricted from roads with ADR tunnel categories D and E.

• Vehicles with code E are restricted from roads with ADR tunnel category E.

• If vehicleAdrTunnelRestrictionCode is not specified, no ADR tunnel restrictions apply.

Notes:

• If travelMode is pedestrian or bicycle, vehicleAdrTunnelRestrictionCode is not considered.

• The vehicleAdrTunnelRestrictionCode and vehicleLoadType parameters are independent; please provide both if applicable.

Values (specify at most one):

• B
• C
• D
• E

Reference:

• European Agreement Concerning the International Carriage of Dangerous Goods by Road (ADR), United Nations, 2019, section 1.9.5 and chapter 8.6

Specifies whether the route calculation should try to avoid ETC-transponder-only toll roads if the vehicle does not have an ETC transponder. Possible values are:

• all: Do not avoid ETC-transponder-only toll roads.
• none: Avoids ETC-transponder-only toll roads.

Default value: all

Specifies the precision of coordinates in the response.
Possible values are:

• default: All coordinates are rounded to 5 digits after the decimal point. Default precision coordinates are targeted towards clients that are sensitive to response sizes. This should be sufficient for most applications.

• full: All coordinates are rounded to 7 digits after the decimal point. Full precision coordinates are targeted towards applications that require precise polyline visualization at high zoom levels.

Default value: default
Other value: full

Specifies how to reconstruct a given polyline or individual legs. Note: This parameter can only be used when a route or legs are provided as part of the request by using a polyline representation format (see the Route geometry representation formats section).
For a description of the use of the given polyline, see the Post Data section of the Calculate Route document. Possible values are:

• normal: Some leeway is allowed when the provided polyline doesn’t exactly match the road network, so that the most sensible route is reconstructed. Use this option in case the given polyline comes from a third party source such as a recorded track, a different routing service, or user input. Consider using the track mode, which is newer and gives better results.

• strict: Reconstruct the given route as close as possible to the given polyline. This might mean that some driving restrictions are violated in order to closely match the original route. Use this option when reconstructing a route previously received from this service.

• track: This mode provides flexibility when the provided route polyline does not align well with the road network, allowing the reconstruction of the most sensible route. The input polyline may have inconsistencies such as gaps and loops. When reconstructing the route using track mode, the algorithm will try to respect the driving restrictions and consider traffic conditions. Use this mode when the given polyline originates from a third-party source such as a recorded track, a different routing service, or user input.

• update: Reconstruct the given route as close as possible to the provided route polyline, ignoring time-dependent driving and legal restrictions in order to keep the input polyline geometry stable. The input polyline is expected to be normalized, without any loops or gaps. Use this option to refresh dynamic data, as required during navigating along your route. Notice: The resulting reconstructed route tries to accurately follow the road network and might result in an illegal route due to potential violation of driving restrictions.

Note: In any of the modes, the algorithm might relax certain restrictions near the origin and destination to offer a more sensible route instead of a no-route-found. This ensures that routes planned with our service can be reconstructed.
Default value: normal
Other values:

• strict
• track
• update

In short, this table summarizes the differences between the modes and restrictions:

Specifies the preferred roadside for arrival at waypoints and the destination. The stop must be positioned at least two meters on the preferred side of the road, otherwise the behavior will default to anySide. Possible values are:

• anySide: Both sides of a road could be used to approach the waypoint and destination. When a vehicle arrives, the stop can be on either the left or right side of the road.

• curbSide: Ensures a minimal number of road crossings at waypoints or the destination. When a vehicle arrives, a stop should be on the right for right-side driving roads or on the left for left-side driving roads.

Default value: anySide
Other value: curbSide

Number of desired alternative routes to be calculated. The value provided:

• Must be an integer in the range 0-5.

• Using a value greater than 0 in conjunction with computeBestOrder set to true is not allowed.

• Fewer alternative routes may be returned if either fewer alternatives exist, or the requested number of alternatives is larger than the service can calculate.

Default value: 0
Maximum value: 5

When maxAlternatives is greater than 0, it allows the definition of computing alternative routes: finding routes that are significantly different from the reference route, or finding routes that are better than the reference route. Possible values are:

• anyRoute: returns alternative routes that are significantly different from the reference route.

• betterRoute: only returns alternative routes that are better than the reference route, according to the given planning criteria (set by routeType). Additionally, there are rules in place ensuring that only routes providing meaningful improvement over the reference route will be proposed as better routes (e.g., a few seconds faster routes won’t be proposed). If there is a road block on the reference route, then any alternative that does not contain any blockages will be considered a better route. The summary in the route response will contain information (see the planningReason parameter) about the reason for the better alternative.

Note: The betterRoute value can only be used when reconstructing a reference route.

Default value: anyRoute
Other values: betterRoute

All alternative routes returned will follow the reference route (see the POST data parameters section) from the origin point of the calculateRoute request for at least this number of meters.

• Can only be used when reconstructing a route.

• The minDeviationDistance parameter cannot be used in conjunction with arriveAt.

All alternative routes returned will follow the reference route (see the POST data parameters section) from the origin point of the calculateRoute request for at least this number of seconds.

• Can only be used when reconstructing a route.

• The minDeviationTime parameter cannot be used in conjunction with arriveAt.

Largest index in the given polyline per route or in the joined polyline per leg (see the POST data parameters section) for which element with the index supportingPointIndexOfOrigin lies on or before the origin point.
The Routing API uses this index as a hint to disambiguate situations where the points of the given polyline in the POST data are not planar, or where they come back close to the origin at a later point in the reconstructed route. In these cases, the supportingPointIndexOfOrigin can explicitly identify if the origin is meant to be on the later part of the route, or not.

• Can only be used when reconstructing a route.

• Cannot be used in conjunction with arriveAt.

Minimum value: 0
Maximum value: Size of the given polyline - 1.

Re-orders the route waypoints with a fast heuristic algorithm to reduce the overall route length. Note that based on the heuristic nature of the algorithm, optimality is not guaranteed. Yields the best results when used in conjunction with routeType shortest.
Possible boolean values are:

• true: compute a better order, if possible

  • Not allowed to be used in conjunction with a maxAlternatives value greater than 0.

  • Not allowed to be used in conjunction with circle waypoints.

  The response will include the reordered waypoint indices in the field optimizedWaypoints.

• false: use the locations in the given order.

  • Not allowed to be used in conjunction with routeRepresentation=none.

Specifies the representation of the set of routes provided as a response.
Possible values are:

• polyline: includes routes in the response as polylines. The polylines are returned in the points fields in the response.

• encodedPolyline: includes routes in the response in the encoded polyline format. The encoded polylines are returned in the encodedPolyline fields and their precisions in the encodedPolylinePrecision fields in the response.

• summaryOnly: as per polyline, but excluding the points fields for the routes in the response.

• none: only includes the optimized waypoint indices but does not include the routes in the response. This parameter value can only be used in conjunction with computeBestOrder=true.

Default value: polyline
Other values:

• encodedPolyline
• summaryOnly
• none

Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time.
Possible values are:

• none: do not compute additional travel times.

• all: compute travel times for all types of traffic information, specifying all results in the fields:

  • noTrafficTravelTimeInSeconds
  • historicTrafficTravelTimeInSeconds
  • liveTrafficIncidentsTravelTimeInSeconds

  being included in the summaries in the route response.

Default value: none
Other value: all

The directional heading of the vehicle, in degrees, starting at true north and continuing in a clockwise direction.

• North is 0 degrees.
• East is 90 degrees.
• South is 180 degrees.
• West is 270 degrees.

Maximum value: 359
Other values: 0-359
Note: The vehicle heading is ignored when doing the base route reconstruction if reconstructionMode is set to strict or update.

Specifies which of the section types is reported in the route response. sectionType can be specified multiple times (e.g., …&sectionType=tollRoad&sectionType=tollVignette&…).
Possible values are:

• carTrain: sections of the route that are car trains.

• ferry: sections of the route that are ferries.

• tunnel: sections of the route that are tunnels.

• motorway: sections of the route that are motorways.

• pedestrian: sections of the route that are only suited for pedestrians.

• tollRoad: sections of the route that require a toll to be paid.

• toll: sections of the route with the usage-based toll collection system (i.e., distance-based tolls, toll bridges and tunnels, weight-based tolls).

• tollVignette: sections of the route that require a toll vignette to be present.

• country: sections indicating which countries the route is in.

• travelMode: sections in relation to the request parameter travelMode.

• traffic: sections of the route that contain traffic information.

• carpool: sections of the route that require use of carpool (HOV/High Occupancy Vehicle) lanes.

• urban: sections of the route that are located within urban areas.

• unpaved: sections of the route that are unpaved.

• lowEmissionZone: sections of the route that are located within low-emission zones.

• roadShields: sections with road shield information. A road shield section contains:

  • roadShieldReferences: A list of references for the road shields (roadShieldReference). Please refer to the structure of a road shield reference object for further information.

  Notes: If this section type is requested, calculateRouteResponse contains the additional field roadShieldAtlasReference.
  Please refer to the notes about the road shield atlas for further information.
  The road shields are only available in these supported countries.

• speedLimit: Sections with legal speed limit information. maxSpeedLimitInKmh: The maximum legal speed limit in kilometers/hour. This can be time-dependent and/or vehicle-dependent.

  • Time can be set by either the departAt or arriveAt request parameter. In the case of a time-dependent speed limit, the section will contain the speed limit effective at the time the planned route would enter this section.

  • Vehicle information can be set by adjusting the travelMode and vehicle* request parameters.

  • Requesting legal speed limits is only valid if travelMode is adjusted to be a motorized vehicle ( car, truck, taxi, bus, van, or motorcycle).

• importantRoadStretch: Sections with important stretches of road information. importantRoadStretch provides a set of street names and/or a set of road numbers that allow the driver to identify and distinguish the course of the route (from other potential routes).

Default value: travelMode
Other values:

• carTrain
• country
• ferry
• motorway
• pedestrian
• tollRoad
• toll
• tollVignette
• traffic
• tunnel
• carpool
• urban
• unpaved
• lowEmissionZone
• roadShields
• speedLimit
• importantRoadStretch

Include toll payment types in the toll section. If a toll section has different toll payment types in its subsections, this toll section is split into multiple toll sections with the toll payment types. Possible values:

• all Include toll payment types in the toll section.
• none Do not include toll payment types in the toll section.

The value all must be used together with sectionType=toll.

Default value: none

Specifies a list of margins in kilowatt-hours (kWh) for computing reachableRouteOffsets.

• Can only be used when all of constantSpeedConsumptionInkWhPerHundredkm, maxChargeInkWh, and currentChargeInkWh are specified.

• The items in the list must be in strictly decreasing order.
• The list is restricted to exactly one item.

Minimum value: 0
Maximum value: 0

Specifies the extended representation of the set of routes provided as a response. <extendedRouteRepresentation> can be specified multiple times (e.g., …&extendedRouteRepresentation=distance&extendedRouteRepresentation=travelTime&extendedRouteRepresentation=consumption&… ). <extendedRouteRepresentation> can only be specified when contentType is json and routeRepresentation is polyline or encodedPolyline.
Possible values are:

• distance: Includes distances to route polyline points in the response.

• travelTime: Includes travel times to route polyline points in the response.

• consumption: Includes consumption values dependent on the vehicleEngineType to route polyline points in the response.

  • Can only be used when the vehicleEngineType is set to electric and the constantSpeedConsumptionInkWhPerHundredkm is specified.

• distance
• travelTime
• consumption

The language parameter determines the language of the returned names of places in general and also of the messages and phonetic translations in guidance.

• Proper nouns (the names of streets, plazas, etc.) are returned in the specified language, or if that is not available, they are returned in an available language that is close to it.

• The currently supported languages are listed on the Supported Languages page. The allowed values for the language parameter are the IETF language tags (or abbreviations in some cases) provided there.

The engine type of the vehicle. When a detailed Consumption model is specified, it must be consistent with the value of vehicleEngineType.
Default value: combustion
Other value: electric

Specifies the speed-dependent component of consumption.

• Provided as an unordered list of speed/consumption rate pairs.

• The list defines points on a consumption curve.

Consumption rates for speeds not in the list are found as follows:

• By linear interpolation, if the given speed lies in between two speeds in the list.

• By linear extrapolation otherwise, assuming a constant (ΔConsumption/ΔSpeed) determined by the nearest two points in the list.

The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed.

• If it only contains a single point, then the consumption rate of that point is used without further processing.

Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed.

• This ensures that extrapolation does not lead to negative consumption rates.

• Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed.

• The minimum and maximum values described here refer to the valid range for the consumption values (expressed in l/100km).

Minimum value: 0.01
Maximum value: 100000.0

Weight of the vehicle in kilograms.
Note: It is mandatory if any of the Efficiency parameters are set.

• This is the same parameter as documented in the Request parameters section.

• It must be strictly positive when used in the context of the Consumption model.

• Weight restrictions are considered.

Minimum value: 1

Specifies the current supply of fuel in liters.
Minimum value: 0.0

Specifies the amount of fuel consumed for sustaining auxiliary systems of the vehicle, in liters per hour. It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc.
Minimum value: 0.0

Specifies the amount of chemical energy stored in one liter of fuel in megajoules (MJ).

• It is used in conjunction with the Efficiency parameters for conversions between saved or consumed energy and fuel.

• For example, energy density is 34.2 MJ/l for gasoline and 35.8 MJ/l for diesel fuel.

• This parameter must be used/required if any *Efficiency parameter is set.

Minimum value: 1.0

Note: This must be paired with decelerationEfficiency.

• Specifies the efficiency of converting chemical energy stored in fuel to kinetic energy when the vehicle accelerates, (i.e., KineticEnergyGained/ChemicalEnergyConsumed).
• ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter.

Minimum value: 0.01
Maximum value: 1/decelerationEfficiency

Note: This must be paired with accelerationEfficiency.

• Specifies the efficiency of converting kinetic energy to saved (not consumed) fuel when the vehicle decelerates (i.e., ChemicalEnergySaved/KineticEnergyLost).
• ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter.

Minimum value: 0.01
Maximum value: 1/accelerationEfficiency

Note: This must be paired with downhillEfficiency.

• Specifies the efficiency of converting chemical energy stored in fuel to potential energy when the vehicle gains elevation (i.e., PotentialEnergyGained/ChemicalEnergyConsumed).
• ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter.

Minimum value: 0.01
Maximum value: 1/downhillEfficiency

Note: This must be paired with uphillEfficiency.

• Specifies the efficiency of converting potential energy to saved (not consumed) fuel when the vehicle loses elevation (i.e., ChemicalEnergySaved/PotentialEnergyLost).
• ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter.

Minimum value: 0.01
Maximum value: 1/uphillEfficiency

Specifies the speed-dependent component of consumption.

• Provided as an unordered list of speed/consumption-rate pairs.

• The list defines points on a consumption curve.

Consumption rates for speeds not in the list are found as follows:

• By linear interpolation, if the given speed lies between two speeds in the list.

• Otherwise, by linear extrapolation using a constant (ΔConsumption/ΔSpeed) derived from the nearest two points in the list.

The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed.

• If it only contains a single point, then the consumption rate of that point is used without further processing.

• Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative consumption rates.

• Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed. The minimum and maximum values described here refer to the valid range for the consumption values (expressed in kWh/100km).

Minimum value: 0.01
Maximum value: 100000.0

Note: This is required only if any *Efficiency parameter is set.

• This is the same parameter as documented in the Request parameters section.

• It must be strictly positive when used in the context of the Consumption model.

• Weight restrictions are considered.

Minimum value: 1

Specifies the current electric energy supply in kilowatt hours (kWh).
Note: Requires maxChargeInkWh to be set.
Minimum value: 0.0
Maximum value: maxChargeInkWh

Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle’s battery.
Note: Requires currentChargeInkWh to be set.
Minimum value: currentChargeInkWh

Specifies the amount of power consumed for sustaining auxiliary systems, in kilowatts (kW). It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc.
Minimum value: 0.0

Specifies the efficiency of converting electric energy into kinetic energy when the vehicle accelerates (i.e., KineticEnergyGained/ ElectricEnergyConsumed).
Notes:

• It must be paired with decelerationEfficiency.
• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1.0

Specifies the efficiency of converting kinetic energy into electric energy when the vehicle decelerates (i.e., ElectricEnergyGained/ KineticEnergyLost).
Notes:

• It must be paired with accelerationEfficiency.

• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1/accelerationEfficiency

Specifies the efficiency of converting electric energy into potential energy when the vehicle gains elevation (i.e., PotentialEnergyGained/ElectricEnergyConsumed).
Notes:

• It must be paired with downhillEfficiency.

• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1.0

Specifies the efficiency of converting potential energy to electric energy when the vehicle loses elevation (i.e, ElectricEnergyGained/PotentialEnergyLost).
Notes:

• It must be paired with uphillEfficiency.

• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1/uphillEfficiency

Specifies the amount of electric energy, in kWh, consumed by the vehicle when gaining 1000 meters of elevation.
Notes:

• It must be paired with recuperationInkWhPerkmAltitudeLoss.

• It cannot be used with accelerationEfficiency, decelerationEfficiency, uphillEfficiency, or downhillEfficiency.

Minimum value: recuperationInkWhPerkmAltitudeLoss
Maximum value: 500.0

Specifies the amount of electric energy, in kWh, gained by the vehicle when losing 1000 meters of elevation.
Notes:

• It must be paired with consumptionInkWhPerkmAltitudeGain.

• It cannot be used with accelerationEfficiency, decelerationEfficiency, uphillEfficiency or downhillEfficiency.

Minimum value: 0.0
Maximum value: consumptionInkWhPerkmAltitudeGain

• Combustion model: 50,6.3:130,11.5

• Electric model: -

• Combustion model: -

• Electric model: 50,8.2:130,21.3

• Combustion model: 1600

• Electric model: 1900

• Combustion model: 55

• Electric model: -

• Combustion model: -

• Electric model: 43

• Combustion model: -

• Electric model: 85

• Combustion model: 0.2

• Electric model: -

• Combustion model: -

• Electric model: 1.7

• Combustion model: 34.2

• Electric model: -

• Combustion model: 0.33

• Electric model: 0.66

• Combustion model: 0.83

• Electric model: 0.91

• Combustion model: 0.27

• Electric model: 0.74

• Combustion model: 0.51

• Electric model: 0.73

• Combustion model: -

• Electric model: 7.0

• Combustion model: -

• Electric model: 3.8

An array of point objects, to be used as input for route reconstruction.
For more information on representing route geometry formats, see the Route geometry representation formats section.

A string in the encoded polyline format, representing the array of points to be used as input for route reconstruction.
The precision used to encode the polyline must be set in the encodedPolylinePrecision field.
For more information on representing route geometry formats, see the Route geometry representation formats section.

The precision used to encode the polyline in the encodedPolyline field.
Must be 5 or 7.
Must be paired with encodedPolyline.

An array of pointWaypoint objects, to be used to represent waypoints when reconstructing a route.

• If specified, the array must not be empty.

• If specified, all location waypoints in the routePlanningLocations will be ignored.

Contains one waypointSourceType and one supportingPointIndex object.

Denotes the source of the waypoint. Possible values:

• USER_DEFINED: a waypoint that was explicitly defined by the user.

An index of an element of the given polyline that denotes the location of the waypoint on the reference route.
For more information on representing polylines, see the Route geometry representation formats section.

• Must fall within the boundaries of the given polyline.

An array of reassessmentParameterSet objects, to be used as input for route reassessment.

• Route reassessment provides information on how some route properties would change based on different input values (note that reassessment does not affect the shape of the route). For example, route reassessment can be used to quantify the impact of air conditioning use on total power consumption.

• If specified, the array must contain exactly one entry.

• A reassessmentParameterSet object is a set of parameters used together to reassess the planned route. Such an object must contain at least one parameter; currently the only supported parameter is auxiliaryPowerInkW.

An array of objects with the parameters for the computation of each leg. If the parameter is such that it is available for use in the query parameters, then its simultaneous use in the query parameters and in the POST data is prohibited, and such a request will be returned with an error.
If the legs field is present in the POST data, then the number of elements in the array must be equal to the number of waypoints + 1.
It is prohibited to use per leg parameters together with circle waypoints.
If there is no need to specify any parameters for some leg, then an empty object must be specified.
It may contain the following fields:

• routeType: specifies the type of optimization used when calculating the leg. For the details, please see the Request parameters section.
  Default value: fastest

• hilliness: specifies the degree of hilliness for a thrilling route. For the details, please see the Request parameters section.
  Default value: normal

• windingness: specifies the level of turns for a thrilling route. For the details, please see the Request parameters section.
  Default value: normal

• routeStop: an object of RouteStop type with additional parameters for the stop at the end of the current leg. It must be omitted if not needed.

• supportingPoints: An array of point objects, to be used as input for leg reconstruction.
  supportingPoints cannot be used for the entire route and per leg simultaneously.
  supportingPoints per leg cannot be used in conjunction with pointWaypoints.
  When using minDeviationTime, minDeviationDistance, or supportingPointIndexOfOrigin, all legs must have non-empty supporting points.
  A supportingPoints array must cover the whole leg, and the itinerary points (an origin, a destination, or a waypoint) must be located at (or very near to) the first and last points.
  supportingPoints must be omitted if not needed.
  When supportingPoints is specified, it must have at least two elements.
  For more information on representing route geometry formats, see the Route geometry representation formats section.

• encodedPolyline: A string in the encoded polyline format, representing the array of points to be used as input for leg reconstruction.
  The precision used to encode the polyline must be set in the encodedPolylinePrecision field.
  encodedPolyline must be omitted if not needed.
  For more information on representing route geometry formats, see the Route geometry representation formats section.

• encodedPolylinePrecision: The precision used to encode the polyline in the encodedPolyline field.
  Must be 5 or 7.
  Must be paired with encodedPolyline.
  Must be omitted if not needed.

• avoids: An array of objects of type Route avoid.
  Must be omitted if not needed.
  Must not be used together with avoid query parameter.

For an example that uses the legs field, please see the POST curl command examples section.

This is an array of strings. Each string should be a 3-character, ISO 3166-1, alpha-3 country code.

• The array describes the countries in which all toll roads with vignettes are to be avoided.

• Toll roads with vignettes in countries not in the array are unaffected.

Note: It is an error to specify both avoidVignette and allowVignette.

This is an array of strings. Each string should be a 3-character, ISO 3166-1, alpha-3 country code.

• The array describes the countries in which toll roads with vignettes are allowed.

• Specifying allowVignette with an array of countries is equivalent to specifying avoidVignette with the array of all countries other than those specified in allowVignette.

• Specifying allowVignette with an empty array is the same as avoiding all toll roads with vignettes.

Note: It is an error to specify both avoidVignette and allowVignette.

Defines areas of certain shapes that should be avoided when planning routes. Supported shapes include rectangles. It can contain one of each supported shapes fields.

This is an array of objects, with a maximum of ten elements. Each object describes an axis-aligned rectangle, defined using the fields southWestCorner and northEastCorner.

• The maximum size of a rectangle is about 160x160 km.
• A rectangle cannot cross the 180th meridian.
• Each rectangle must lie between -80 and +80 degrees of latitude.

The south-west corner of a rectangle. It is an object consisting of a latitude and a longitude field, each field containing the value in degrees as a number.

The north-east corner of a rectangle. It is an object consisting of a latitude and a longitude field, each field containing the value in degrees as a number.

Specifies the waiting time at route stops (including charging time). It must be 0 in the last leg (the destination).
Default value: 0

Specifies the entry points for the stop at the end of the current leg. The route to the stop is calculated based on these entry points.

• Entries with the same location are not allowed.

• If specified, the array must not be empty.

Specifies the index of the preferred entry point. An index of 0 denotes the first entry point. Selecting an entry point as preferred does not guarantee that it will be used as the destination.

• Can only be specified if entryPoints are set.

• Must be less than the number of entryPoints.

The latitude of the entry point. Required.

The longitude of the entry point. Required.

Specifies the name of the road attribute for route calculation to try to avoid. Possible values are listed under Avoid parameter possible values.

The service whitelists response headers that browsers are allowed to access.
Value: Content-Length

The service allows cross-origin resource sharing.
Value: * (wildcard)

The service supports HTTP compression, if requested by the client.
Value: gzip

The format of the response. The service supports specifying the desired response format. See the contentType parameter.
Values:

• application/json; charset=utf-8
• application/javascript; charset=utf-8

The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain. It is supported by HTTP/1.1 clients. It may not be supported by HTTP/1.0 clients.
Values:

• no-cache
• no-transform

The Pragma general-header field is used to specify directives that might apply to any recipient along the request/response chain. It is supported by HTTP/1.0 clients.
Value: no-cache

This is an identifier for the request. If Tracking-ID was specified in the request headers, it contains the same value. Otherwise, it may contain a generated value.

This may be sent for deprecated features.

OK: A route or range was calculated and the body of the response contains the data for a successful response.

Bad request:

• One or more parameters were incorrectly specified.
• Some parameters are mutually exclusive.

• The points in the route request are not connected by the road network.

• The points in the request are not near enough to a road.

Permission or authentication issues:

• Forbidden
• Not authorized
• Account inactive

Not Found: The requested resource could not be found, but it may be available again in the future.

Method Not Allowed: The client used an HTTP method other than GET or POST.

Request timeout: The client took too long to transmit the request.

The request URI is too long.

Unsupported media type.

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

An error occurred while processing the request. Please try again later. This can also indicate that the request reached an internal computation time threshold and timed out.

Internal network connectivity issue.

Service currently unavailable.

Internal network connectivity issue.

Service not found.

The request may return more than one route.
Each object has at least a summary field and a legs field. It may contain other fields depending on the request parameters.

The summary of a route, or of a route leg.
The summary object may be extended with new fields in the future; clients should ignore fields they do not recognize.

• Included if reassessmentParameterSets is specified.

• Each object in the array corresponds to the entry with the same index in reassessmentParameterSets (see the POST data parameters) and contains the results of a reassessment using the corresponding reassessmentParameterSet.

• The objects describe particular aspects of the route as a whole. Their values may differ from those reported in the route summary.

• If the reassessmentParameterSet contains auxiliaryPowerInkW, then the corresponding object may contain the following fields (see individual field descriptions for details):

  • batteryConsumptionInkWh
  • reachableRouteOffsets

• The objects in this array may be extended with new fields in the future; clients should ignore fields they do not recognize.

A description of a part of a route, comprised of an array of points.

• Contains the summary field and may contain the points, encodedPolyline, and encodedPolylinePrecision fields.

• Each additional waypoint provided in the request will result in an additional leg in the returned route.

Each object in the array is a location on the surface of the globe defined by its latitude and longitude fields.
For more information on representing route geometry formats, see the Route geometry representation formats section.

A string in the encoded polyline format, representing the array of points describing a part of a route.
The precision used to encode the polyline is set in the encodedPolylinePrecision field. The precision reflects the selected coordinatePrecision, i.e., the precision is 5 with default, and 7 with full.
For more information on representing route geometry formats, see the Route geometry representation formats section.

The precision used to encode the polyline in the encodedPolyline field.

This array is available inside routeobjects.

• Contains one or more section objects.

• The structure of section objects is given below.

Index of the first point (offset 0) in the route this section applies to (only included for a routeRepresentation polyline).

Index of the last point (offset 0) in the route this section applies to (only included for a routeRepresentation polyline).

A 3-character ISO 3166-1 alpha-3 country code.

Type of the incident.

• Can currently be JAM, ROAD_WORK, ROAD_CLOSURE, or OTHER.

• See the tec field for detailed information.

The effective speed of the incident in km/h, averaged over its entire length.

The magnitude of delay caused by the incident.
Possible values:

• 0: unknown

• 1: minor

• 2: moderate

• 3: major

• 4: undefined, used for road closures and other indefinite delays

These values correspond to the values of the response field magnitudeOfDelay

Details of the traffic event. It uses the definitions in the TPEG2-TEC standard. It can contain the effectCode and causes fields.
A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets.

The effect on the traffic flow. Contains a value in the tec001:EffectCode table, as defined in the TPEG2-TEC standard. Can be used to color-code traffic events according to severity.

Each object in the array describes one cause of the traffic event.

• It can contain mainCauseCode and subCauseCode fields.

• It can be used to define iconography and descriptions.

The main cause of the traffic event. Contains a value in the tec002:CauseCode table, as defined in the TPEG2-TEC standard.
A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets.

The sub-cause of the traffic event. Contains a value in the sub cause table defined by the mainCauseCode, as defined in the TPEG2-TEC standard.
A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets.

A unique ID of the traffic incident.

The estimated travel time in seconds. Note that even when traffic=false, travelTimeInSeconds still includes the delay due to traffic.

The delay in seconds compared to free-flow conditions according to real-time traffic information.

The portion of the route or leg, expressed in meters, that is affected by traffic events which cause the delay.

The estimated travel time in seconds calculated as if there are no delays on the route due to traffic conditions (e.g., congestion). Included if requested using the computeTravelTimeFor parameter.

The estimated travel time in seconds calculated using time-dependent historic traffic data. Included if requested using the computeTravelTimeFor parameter.

The estimated travel time in seconds calculated using real-time speed data. Included if requested using the computeTravelTimeFor parameter.

The distance (in meters) from the origin point of the calculateRoute request to the first point where this route forks off from the reference route.

• If the route is identical to the reference route, then this field is set to the length of the route.

• Included in all alternative (but not reference) route summary fields.

The travel time (in seconds) from the origin point of the calculateRoute request to the first point where this route forks off from the reference route.

• If the route is identical to the reference route, then this field is set to the estimated travel time of the route.

• Included in all alternative (but not reference) route summary fields.

The coordinates of the first point following the origin point of the calculateRoute request where this route forks off from the reference route.

• If the route is identical to the reference route, then this field is set to the coordinates of the last point on the route.

• Included in all alternative (but not reference) route summary fields.

The estimated fuel consumption in liters using the Combustion Consumption Model. Included if:

• The vehicleEngineType is set to combustion.

• The constantSpeedConsumptionInLitersPerHundredkm is specified.

• The value will be non-negative (i.e., positive).

The estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model.

• Included if:

  • vehicleEngineType is set to electric.

  • constantSpeedConsumptionInkWhPerHundredkm is specified.

• The value of batteryConsumptionInkWh includes the recuperated electric energy and can therefore be negative (which indicates gaining energy).

• If both maxChargeInkWh and currentChargeInkWh are specified, recuperation will be capped to ensure that the battery charge level never exceeds maxChargeInkWh.

• If neither maxChargeInkWh nor currentChargeInkWh are specified, unconstrained recuperation is assumed in the consumption calculation.

This field is included if chargeMarginsInkWh is specified. It is not present in the leg summary field. Each object in the array corresponds to an entry in chargeMarginsInkWh, and describes the reachable point on the route with respect to the charge margin specified there. Effectively, the farthest the vehicle can go on the route on its current charge, without depleting the battery beyond the specified margin.

• Objects in the array contain the following fields:

  • chargeMarginInkWh: the charge margin this reachable point is calculated for.

  • point: location of the reachable point defined as a latitude longitude pair.

  • pointIndex: largest index in the polyline of the route for which points[pointIndex] lies on or before point.

  • routeOffsetInMeters: the distance from the start of the route to the reachable point.

• Note that:

  • If currentChargeInkWh is less than or equal to chargeMarginInkWh, routeOffsetInMeters is zero.

  • routeOffsetInMeters is at most lengthInMeters.

  • Charging stops are ignored in the computation so that e.g., live traffic is used as if driving past any charging station.

A description of an optimized sequence of waypoints. It shows the index from the user-provided waypoint sequence for the original and optimized list. For instance, a response:

1
{
2
  "optimizedWaypoints": [
3
    {
4
      "providedIndex": 0,
5
      "optimizedIndex": 1
6
    },
7
    {
8
      "providedIndex": 1,
9
      "optimizedIndex": 2
10
    },
11
    {
12
      "providedIndex": 2,
13
      "optimizedIndex": 0
14
    }
15
  ]
16
}

means that:

• The original sequence is [0, 1, 2].

• The optimized sequence is [1, 2, 0].

Since the index starts by 0 the original is “first, second, third”, while the optimized is “second, third, first”.

The estimated departure time for the route or leg. Specified as a dateTime.

The estimated arrival time for the route or leg. Specified as a dateTime.

Each object in the array represents an effective parameter or a data used when calling the Calculate Route API. Each object has fields key and value both containing a string describing the input and its value.

The original HTTP status code as listed in the response codes (note: included for content type jsonp only).

The reason for a better route proposal. Can currently be:

• Blockage in case the reference route contains road blockages. The returned value is implementation-defined in case both reasons for a better proposal are applicable to the same route.

• Better_Proposal in case the alternative type is better than the reference route, according to the given planning criteria (set by routeType).

This field is included in the response only if the route is requested with alternativeType=betterRoute. This field is not present in the leg summary field.

This field is included if extendedRouteRepresentation is used.

• It always contains entries for the first and the last point in the route.

• For any pair of consecutive entries in the progress array, progress for pointIndex values that are not explicitly present and are enclosed by said pair, can be linearly interpolated by summing up straight line distances of the leg points.

• The Haversine formula is precise enough to compute such distances.

A progress point object may contain the following members:

• pointIndex: index of the point (offset 0) in the route this object applies to.

• distanceInMeters: distance (in meters) from the start of the route to this point. This field is included if the extendedRouteRepresentation value distance is used.

• travelTimeInSeconds: travel time (in seconds) from the start of the route to this point. This field is included if the extendedRouteRepresentation value travelTime is used.

• batteryConsumptionInkWh: electric energy consumption (in kilowatt hours) from the start of the route to this point. This field is included if the extendedRouteRepresentation value consumption is used and the vehicleEngineType is set to electric. See also the batteryConsumptionInkWh in summary section.

The index of the waypoint at the end of the leg that corresponds to:

• The index of this waypoint in the list of waypoints from the routePlanningLocations base path parameter in the request (the first waypoint has an index equal to 0).

• The index of this waypoint in the pointWaypoints field when reconstructing a route.

This field is not provided if the end of the leg corresponds to the destination or to a new charging waypoint that is not present in the request.

Contains the value of pauseTimeInSeconds, if it was specified for the corresponding leg. This field is not present in the route summary field.

Identifies the entry point that was used for the route at the end of the leg.
This index corresponds to the position of this entry point in the list of entry points within the respective leg.
The first entry point has an index equal to 0. This field is only present if the leg had entryPoints in the request.

The base URL of the Road Shields service to fetch the road shield atlas and metadata resources.
Currently available resources are:

• sprite.png
• sprite.json

We recommend to cache the sprite atlas (sprite.png) and metadata (sprite.json) as it changes infrequently and is large compared to a typical road shield description.
Please refer to the Road Shield service for further information. The returned road shield references correspond to the asset names in the Road Shield service.

The integer value of importance. The index starts from 0, and a lower value means higher importance. The index is needed for two reasons:

1. To understand which stretch is the most important (for example, if it is necessary to display a smaller number of stretches).
2. To group different sections that belong to the same stretch (since there may be gaps in one stretch for various reasons).

An object contains a text field with the name of a street.

An array of objects of type RoadNumber. All items are sorted in descending order of display priority.
The RoadNumber object contains a text field with the road number.

Contains the response section type.

• The COUNTRY sections span between country border crossings from the departure, or to the destination.

  • The section additionally contains countryCode.

  • If the route has disjointed parts in the same country, there will be several sections with the same countryCode.

  • If no country can be assigned to a part of the route, as for example in international waters, there may be no country section for this part.

• When requested using includeTollPaymentTypes, a TOLL section optionally contains tollPaymentTypes.

• A TOLL_VIGNETTE section additionally contains a countryCode since toll vignettes are often specific to a country.

• A TRAFFIC section may additionally contain any of the following: simpleCategory, effectiveSpeedInKmh, delayInSeconds, magnitudeOfDelay, tec, eventId.

• TRAVEL_MODE sections cover the whole route. Each section’s travel mode is reported in travelMode .

• CARPOOL sections contain parts of the route that are only open to HOV (high-occupancy vehicles) at the time of traversal. Roads with at least one unrestricted lane are not part of a CARPOOL section.

• ROAD_SHIELDS sections contain an array of roadShieldReference objects. Please refer to the structure of a road shield reference object for further information.

• An IMPORTANT_ROAD_STRETCH section additionally contains the importantRoadStretchIndex field, and contains streetName or roadNumbers fields (or both).

This field is either set to the value given to the request parameter travelMode, if this travel mode is possible, or to other which indicates that the given mode of transport is not possible in this section. This field can only be used within sections of type TRAVEL_MODE.

The tollPaymentTypes array appears in toll sections if includeTollPaymentTypes=all. Each element of tollPaymentTypes represents a toll payment type. This field can only be used within sections of type TOLL.

Possible toll payment types are:

• CASH_COINS_AND_BILLS: Cash can be used including coins and bills.

• CASH_BILLS_ONLY: Cash can be used, but bills only, e.g., 10 euros.

• CASH_COINS_ONLY: Cash can be used, but coins only, e.g., 20 cents.

• CASH_EXACT_CHANGE: Cash is used but the exact amount must be provided.

• CREDIT_CARD: Credit cards are accepted.

• DEBIT_CARD: Bank/debit cards are accepted.

• TRAVEL_CARD: Travel cards are accepted.

• ETC: Electronic toll collect either via camera or transponder.

• ETC_TRANSPONDER: Electronic toll collect via transponder.

• ETC_VIDEO_CAMERA: Electronic toll collect via camera.

• SUBSCRIPTION: Toll collect based on subscription.