Common Routing Parameters

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 the two fields latitude and longitude each containing a number, and expressed in the same reference frame and with the same constraints as for the location type.
Example: {"latitude": 52.37245, "longitude": 4.89406}

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

Comma-separated speedInkmh,consumptionInLitersPerHundredkm pair with the following constraint: The speedInkmh values must be in the range [0.0, 255.0].
Example: 15.5,10.0

Comma-separated speedInkmh,consumptionInkWhPerHundredkm pairs with the following constraint: The speedInkmh values must be in the range [0.0, 255.0].
Example: 15.5,8.0

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.

Base URL for calling 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 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.

Authorization key to access the API.
Value: Your valid API Key.

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

Specifies which data should be reported for diagnostic purposes. A possible value is: effectiveSettings.

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

• In the case of defaulted parameters, the default will be reflected where the parameter was not specified by the caller.

Default value: effectiveSettings

The date and time of departure from the origin point.

• Departure times apart from now must be specified as a dateTime.

• When a time zone offset is not specified, it will be assumed to be that of the origin point.

• 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.

• When a time zone offset is not specified it will be assumed to be that of the destination point.

The arriveAt parameter cannot be used in conjunction with:

• departAt
• minDeviationDistance
• minDeviationTime

It cannot be used in calculateReachableRange requests.
Value: dateTime

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

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

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

• short: Route calculation is optimized such that a good compromise between small travel time and short travel distance is achieved.

• eco: Route calculation is optimized such that a good compromise between small travel time and low fuel or energy consumption is achieved.

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

  • You can choose the level of turns included and also the degree of hilliness.

  • See the hilliness and windingness parameters to set this.

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

Default value: fastest

Possible values are:

• true: Do consider 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 that are 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 can be specified multiple times (e.g., ...&avoid=motorways&avoid=ferries&...).
Possible values are:

• tollRoads: Avoids toll roads.

• motorways: Avoids motorways.

• ferries: Avoids ferries.

• unpavedRoads: Avoids unpaved roads.

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

• alreadyUsedRoads:

  • Avoids using the same road multiple times.

  • This is most useful in conjunction with routeType=thrilling.

• borderCrossings: Avoids crossing country borders.

• tunnels: Avoids tunnels.

• carTrains: Avoids car trains.

• lowEmissionZones: Avoids low-emission zones.

Note: In calculateReachableRange requests, the value alreadyUsedRoads must not be used.

Specifies something that the route calculation should try to prefer when determining the route.
Possible value:

• handsFreeDriving: Prefer stretches that allow for hands-free driving.

  • If this parameter is set, then handsFreeDrivingCapability must also be set.

Specifies the hands-free driving capability of the vehicle. The available hands-free driving data is matched against handsFreeDrivingCapability in order to filter for the subset of data that applies to the specific capability of the vehicle.

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

The mode of travel for the requested route.

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

• Where the requested travelMode is not available for a particular section, the travelMode field of the response for that section 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.

• In calculateReachableRange requests, the values bicycle and pedestrian must not be used.

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 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 are 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 the route calculation should try to avoid ETC-transponder-only toll roads when determining the route if a 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.

If this parameter is not specified, ETC-transponder-only toll roads are not avoided.

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 supportingPoints. For a description of supportingPoints see the Post Data section of the Calculate Route or Calculate Reachable Range document. Possible values are:

• normal: Some leeway is allowed when the provided polyline doesn't exactly match the road network, such that a 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. Please consider using the track mode, it 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 preference of roadside on arrival to waypoints and destination. Stop on the road has to be set at least two meters to the preferred side, 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, a stop could be either on a left side or a right side.

• 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 the right-side driving road or on a left for the left-side driving road.

Default value: anySide
Other value: curbSide

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 previous "Common Routing 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.0
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.0
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.0
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.0
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 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 kWh/100km).

Minimum value: 0.01
Maximum value: 100000.0

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

• This is the same parameter as documented in the previously defined Common Routing 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 to 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.0
Maximum value: 1/decelerationEfficiency

Specifies the efficiency of converting kinetic energy to 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.0
Maximum value: 1/accelerationEfficiency

Specifies the efficiency of converting electric energy to 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.0
Maximum value: 1/downhillEfficiency

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.0
Maximum value: 1/uphillEfficiency

Specifies the electric energy in kWh consumed by the vehicle through 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 electric energy in kWh gained by the vehicle through 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

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 to avoid 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.
• It cannot cross the 180th meridian.
• It must be 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.

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 client.
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.

• A reachable range consistent with the given parameters could not be found.

Permission, capacity, or authentication issues:

• Forbidden
• Not authorized
• Account inactive
• Account over queries per second limit

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

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

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

Requested 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.