Sorry, you need to enable JavaScript to visit this website.

Common Routing Parameters

This page documents fundamental route planning parameters that can be used in the Calculate Route and Calculate Reachable Range services.

Please be aware that this document does not specify the complete request or response format. To maintain forward compatibility you must be able to process responses with additional non-documented data fields. Our deprecation policy only covers the documented subset of these formats.

Types

The table below describes a subset of the types that can be used in the Calculate Route and Calculate Reachable Range services.

Type Description Example
point Latitude, longitude pair (in EPSG4326 projection), with the following constraints:

  • Latitude values must be in the range -90..+90 inclusive.
  • Longitude values must be in the range -180..+180 inclusive.
52.37245,4.89406
dateTime A date and time specified in RFC-3339 format with an optional time zone offset.
  • 1996-12-19T16:39:57
  • 1996-12-19T16:39:57-08:00
CombustionConstantSpeedConsumptionPair Comma-separated speedInkmh,consumptionInLitersPerHundredkm pairs with the following constraints:

  • The type of speedInkmh and consumptionInLitersPerHundredkm is float.
  • The speedInkmh values must be in the range [0.0, 255.0].
15.5,10.0
ElectricConstantSpeedConsumptionPair Comma-separated speedInkmh,consumptionInkWhPerHundredkm pairs with the following constraints:

  • The type of speedInkmh and consumptionInkWhPerHundredkm is float.
  • The speedInkmh values must be in the range [0.0, 255.0].
15.5,8.0

Request

Headers

The table below describes HTTP request headers of particular interest to Calculate Route and Calculate Reachable Range service clients. Required headers must be used or the call will fail. Optional headers, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional header is not used, it is shown in the table. The order of request headers is not important.

Header Description Req'd? Values Default Value
[Accept-Encoding] Requests that the response be compressed. No gzip
[Content-Type] Specifies the MIME type of the body of the request. Required for POST requests. No
  • application/xml
  • application/json
[Tracking-ID] 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.
No

Base Path Parameters

The table below describes a subset of the parameters that can be used in the Calculate Route and Calculate Reachable Range services. Required parameters must be used, or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

Parameter Description Req'd? Type / Values Default Value
baseURL Base URL for calling the API. Yes api.tomtom.com
[contentType] The content type of the response structure. If the content type is jsonp, a callback method can be specified in the query parameters. No
  • xml
  • json
  • jsonp
xml

Request Parameters

Request Parameters are presented in two sections: the Common Routing Parameters section describes common parameters that affect the routing algorithm in various ways, while the Consumption Model Parameters section explains a particular subset of parameters that define a detailed Consumption Model.

Common Routing Parameters

This section presents a set of loosely connected parameters that influence the operation of the routing algorithm. While some of them are associated, the majority can be used independently of the others.

Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table. The order of request parameters is not important.

Parameter Description Req'd? Type / Values Default Value
key Authorization key for access to the API Yes API Key
[callback] Specifies the jsonp callback method. Only used when contentType is jsonp. No string callback
[report] Specifies which data should be reported for diagnosis purposes. Possible values:

  • 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.
No
  • effectiveSettings
[departAt] 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 value must be in the future. The departAt parameter cannot be used in conjunction with arriveAt. No
  • now
  • dateTime
now
[arriveAt] 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 value must be in the future. The arriveAt parameter cannot be used in conjunction with departAt, minDeviationDistance or minDeviationTime. It cannot be used in calculateReachableRange requests. No dateTime
[routeType] The type of route requested. Notes on specific values:

  • fastest returns the fastest route.
  • shortest returns the shortest route by distance.
  • eco routes balance economy and speed.
  • thrilling 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 for how to set this.

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

No
  • fastest
  • shortest
  • eco
  • thrilling
fastest
[traffic] Possible values:

  • 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.
No boolean true
[avoid] Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times. Possible values:

  • 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. Most useful in conjunction with routeType=thrilling.

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

No
  • tollRoads
  • motorways
  • ferries
  • unpavedRoads
  • carpools
  • alreadyUsedRoads
[travelMode] 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 element of the response for that section will be other.

Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas.

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

No
  • car
  • truck
  • taxi
  • bus
  • van
  • motorcycle
  • bicycle
  • pedestrian
car
[hilliness] Degree of hilliness for thrilling route. This parameter can only be used in conjunction with routeType=thrilling. No
  • low
  • normal
  • high
normal
[windingness] Level of turns for thrilling route. This parameter can only be used in conjunction with routeType=thrilling. No
  • low
  • normal
  • high
normal
[vehicleMaxSpeed] Maximum speed of the vehicle in km/hour. A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning. A non-zero value may be overridden during route planning. No integer 0
[vehicleWeight] Weight of the vehicle in kilograms.

  • If a detailed Consumption Model is specified, refer to section Consumption Model Parameters below for the documentation of vehicleWeight.
  • If no detailed Consumption Model is specified and the value of vehicleWeight is non-zero, then weight restrictions are considered.
  • In all other cases, this parameter is ignored.
No integer 0
[vehicleAxleWeight] Weight per axle of the vehicle in kg. A value of 0 means that weight restrictions per axle are not considered. No integer 0
[vehicleLength] Length of the vehicle in meters. A value of 0 means that length restrictions are not considered. No float 0
[vehicleWidth] Width of the vehicle in meters. A value of 0 means that width restrictions are not considered. No float 0
[vehicleHeight] Height of the vehicle in meters. A value of 0 means that height restrictions are not considered. No float 0
[vehicleCommercial] Vehicle is used for commercial purposes and thus may not be allowed to drive on some roads. No boolean false
[vehicleLoadType] Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries.

Use these for routing in the US:

  • USHazmatClass1 Explosives
  • USHazmatClass2 Compressed gas
  • USHazmatClass3 Flammable liquids
  • USHazmatClass4 Flammable solids
  • USHazmatClass5 Oxidizers
  • USHazmatClass6 Poisons
  • USHazmatClass7 Radioactive
  • USHazmatClass8 Corrosives
  • USHazmatClass9 Miscellaneous

Use these for routing in all other countries:

  • otherHazmatExplosive Explosives
  • otherHazmatGeneral Miscellaneous
  • otherHazmatHarmfulToWater Harmful to water

vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck.

No
  • USHazmatClass1
  • USHazmatClass2
  • USHazmatClass3
  • USHazmatClass4
  • USHazmatClass5
  • USHazmatClass6
  • USHazmatClass7
  • USHazmatClass8
  • USHazmatClass9
  • otherHazmatExplosive
  • otherHazmatGeneral
  • otherHazmatHarmfulToWater

Consumption Model Parameters

Routing API provides a set of parameters for a detailed description of vehicle-specific Consumption Model.
These parameters can be specified in a calculateRoute request, and they must be specified in a calculateReachableRange request.

Depending on the value of vehicleEngineType we support two principal Consumption Models: Combustion and Electric. Specifying parameters that belong to different models in the same request is an error.

Consumption Model cannot be used with travelMode values bicycle and pedestrian.

Parameter Constraints

In both Consumption Models, explicitly specifying some parameters requires specifying some others as well. These dependencies are:

  • All parameters require constantSpeedConsumption* to be specified by the user. It is an error to specify any other consumption model parameter (with the exception of vehicleWeight) if constantSpeedConsumption* is not specified.
  • accelerationEfficiency and decelerationEfficiency must always be specified as a pair (i.e. both or none).
  • If accelerationEfficiency and decelerationEfficiency are specified, product of their values must not be greater than 1 (to prevent perpetual motion).
  • uphillEfficiency and downhillEfficiency must always be specified as a pair (i.e. both or none).
  • If uphillEfficiency and downhillEfficiency are specified, product of their values must not be greater than 1 (to prevent perpetual motion).
  • If *Efficiency parameters are specified by the user, then vehicleWeight must also be specified. When vehicleEngineType is combustion, fuelEnergyDensityInMJoulesPerLiter must be specified as well.
  • maxChargeInkWh and currentChargeInkWh must always be specified as a pair (i.e. both or none).

Note that if only constantSpeedConsumption* is specified, no other consumption aspects are taken into account, i.e. slopes and vehicle acceleration are not considered for consumption computations.

Selecting the Consumption Model

There are two available Consumption Models: Combustion and Electric. A model is selected by specifying the corresponding constantSpeedConsumption* parameter and possibly further parameters that belong to the same model. The chosen model must match the value of the vehicleEngineType parameter.

Parameter Description Req'd? Type / Values Default Value
[vehicleEngineType] Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType. No
  • combustion
  • electric
combustion
The Combustion Consumption Model

The Combustion Consumption Model is used when vehicleEngineType is set to combustion.

The table below describes all of the parameters that can be specified in a request using the Combustion Model. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table. The order of parameters in a request is not important.

Parameter Description Req'd? Type / Values Default Value Min Value Max Value
constantSpeedConsumptionInLitersPerHundredkm 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).

Yes Colon-delimited list of CombustionConstantSpeedConsumptionPairs 0.01 100000.0
[vehicleWeight] Weight of the vehicle in kilograms. This is the same parameter as documented in the Common Routing Parameters section above.
It is mandatory if any of the *Efficiency parameters are set.
It must be strictly positive when used in the context of the Consumption Model. Weight restrictions are considered.
Yes - if any *Efficiency parameter is set integer 1
[currentFuelInLiters] Specifies the current supply of fuel in liters. No float 0.0
[auxiliaryPowerInLitersPerHour] 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.
No float 0.0
[fuelEnergyDensityInMJoulesPerLiter] 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. Yes - if any *Efficiency parameter is set float 0.0
[accelerationEfficiency] 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. No - must be paired with decelerationEfficiency float 0.0 1/decelerationEfficiency
[decelerationEfficiency] 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.
No - must be paired with accelerationEfficiency float 0.0 1/accelerationEfficiency
[uphillEfficiency] 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. No - must be paired with downhillEfficiency float 0.0 1/downhillEfficiency
[downhillEfficiency] 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.
No - must be paired with uphillEfficiency float 0.0 1/uphillEfficiency
The Electric Consumption Model

The Electric Consumption Model is used when vehicleEngineType is set to electric.

The table below describes all of the parameters that can be specified in a request using the Electric Model. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table. The order parameters in a request is not important.

Parameter Description Req'd? Type / Values Default Value Min Value Max Value
constantSpeedConsumptionInkWhPerHundredkm 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).

Yes Colon-delimited list of ElectricConstantSpeedConsumptionPairs 0.01 100000.0
[vehicleWeight] Weight of the vehicle in kilograms. This is the same parameter as documented in the Common Routing Parameters section above.
It is mandatory if any of the *Efficiency parameters are set.
It must be strictly positive when used in the context of the Consumption Model. Weight restrictions are considered.
Yes - if any *Efficiency parameter is set integer 1
[currentChargeInkWh] Specifies the current electric energy supply in kilowatt hours (kWh). No - requires maxChargeInkWh to be set float 0.0 maxChargeInkWh
[maxChargeInkWh] Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle's battery. No - requires currentChargeInkWh to be set float currentChargeInkWh
[auxiliaryPowerInkW] 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.
No float
[accelerationEfficiency] Specifies the efficiency of converting electric energy to kinetic energy when the vehicle accelerates (i.e. KineticEnergyGained/ElectricEnergyConsumed). No - must be paired with decelerationEfficiency float 0.0 1/decelerationEfficiency
[decelerationEfficiency] Specifies the efficiency of converting kinetic energy to electric energy when the vehicle decelerates (i.e. ElectricEnergyGained/KineticEnergyLost). No - must be paired with accelerationEfficiency float 0.0 1/accelerationEfficiency
[uphillEfficiency] Specifies the efficiency of converting electric energy to potential energy when the vehicle gains elevation (i.e. PotentialEnergyGained/ElectricEnergyConsumed). No - must be paired with downhillEfficiency float 0.0 1/downhillEfficiency
[downhillEfficiency] Specifies the efficiency of converting potential energy to electric energy when the vehicle loses elevation (i.e. ElectricEnergyGained/PotentialEnergyLost). No - must be paired with uphillEfficiency float 0.0 1/uphillEfficiency
Sensible Values of Consumption Parameters

It is possible that a particular set of consumption parameters is rejected, even though it might fulfill all the explicit requirements specified above. This will happen when the value of a specific parameter, or a combination of values of several parameters, is deemed to lead to unreasonable magnitudes of consumption values. If that happens, it most likely indicates an input error, as proper care is taken to accommodate all sensible values of consumption parameters. In case a particular set of consumption parameters is rejected, the accompanying error message will contain a textual explanation of the reason(s).

Example

To give the feeling of the magnitudes of reasonable parameter values, the table below provides an example of sensible values for the Combustion and Electric models.

Parameter Combustion Model Electric Model
constantSpeedConsumptionInLitersPerHundredkm 50,6.3:130,11.5
constantSpeedConsumptionInkWhPerHundredkm 50,8.2:130,21.3
vehicleWeight 1600 1900
currentFuelInLiters 55
currentChargeInkWh 43
maxChargeInkWh 85
auxiliaryPowerInLitersPerHour 0.2
auxiliaryPowerInkW 1.7
fuelEnergyDensityInMJoulesPerLiter 34.2
accelerationEfficiency 0.33 0.66
decelerationEfficiency 0.83 0.91
uphillEfficiency 0.27 0.74
downhillEfficiency 0.51 0.73

POST Data Parameters

Some parameters can be provided using HTTP POST method. The POST data can be in either XML or JSON format, see the [Content-Type] header. All POST Data Parameters are optional. It is an error to use the HTTP POST method if no POST Data Parameters are provided.

There is an upper limit on the total size of the POST data. Exceedance of this limit results in a response with Response Code 400, indicating invalid POST data. The client must not rely on the exact value of this limit. The current limit is 30 MB.

Compressed POST data is not supported. Requests with compressed POST data results in a response with Response Code 415.

When using XML format for the POST data, the root element must be <postData>.

The table below describes a subset of the parameters that can be used in the Calculate Route and Calculate Reachable Range services.

Parameter Description
<avoidVignette> List of 3-character ISO 3166-1 alpha-3 country codes of countries in which all toll roads with vignettes are to be avoided. Toll roads with vignettes in countries not in the list are unaffected. It is an error to specify both avoidVignette and allowVignette.
<allowVignette> List of 3-character ISO 3166-1 alpha-3 country codes of countries in which toll roads with vignettes are allowed. Specifying allowVignette with some countries X is equivalent to specifying avoidVignette with all countries but X. Specifying allowVignette with an empty list is the same as avoiding all toll roads with vignettes. It is an error to specify both avoidVignette and allowVignette.
<avoidAreas> A list of shapes to avoid for planning routes. Supported shapes include <rectangles>. Can contain one of each supported shapes element.
<rectangles> List of <rectangle> elements. The maximum number of <rectangle> elements is ten.
<rectangle> Axis aligned rectangle, defined as <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.
<southWestCorner> The south-west corner of a rectangle, defined as a latitude longitude pair (point).
<northEastCorner> The north-east corner of a rectangle, defined as a latitude longitude pair (point).

XML request content example

<postData>
  <avoidVignette>
    AUS,CHE
  </avoidVignette>
  <avoidAreas>
    <rectangles>
      <rectangle>
        <southWestCorner latitude="48.81851" longitude="2.26593"/>
        <northEastCorner latitude="48.90309" longitude="2.41115"/>
      </rectangle>
    </rectangles>
  </avoidAreas>
</postData>

JSON request content example

{
  "avoidVignette": [
    "AUS",
    "CHE"
  ],
  "avoidAreas": {
    "rectangles": [
      {
        "southWestCorner": {"latitude": 48.81851, "longitude": 2.26593},
        "northEastCorner": {"latitude": 48.90309, "longitude": 2.41115}
      }
    ]
  }
}

Response

Response Headers

The table below describes HTTP response headers of particular interest to Calculate Route and Calculate Reachable Range service clients.

Header Description Values
Access-Control-Expose-Headers The service whitelists response headers that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin The service allows cross-origin resource sharing. *
Content-Encoding The service supports HTTP compression, if requested by the client. gzip
Content-Type The format of the response. The service supports specifying the desired response format. See contentType parameter.
  • application/xml; charset=utf-8
  • application/json; charset=utf-8
  • application/javascript; charset=utf-8
Cache-Control The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain. Supported by HTTP/1.1 clients. May not be supported by HTTP/1.0 clients. no-cache, no-transform
Pragma The Pragma general-header field is used to specify directives that might apply to any recipient along the request/response chain. Supported by HTTP/1.0 clients. no-cache
Tracking-ID An identifier for the request. If Tracking-ID was specified in the request headers, contains the same value. Otherwise may contain a generated value.

Response Codes

The table below describes HTTP response codes of particular interest to Calculate Route and Calculate Reachable Range service clients.

Code Meaning and Possible Causes
200 OK: a route or range was calculated and the body of the response contains the data for a successful response.
400 Bad request: one or more parameters were incorrectly specified, are mutually exclusive, the points in the route request are not connected by the road network or the points in the request are not near enough to a road.
403 Permission, capacity, or authentication issues:

  • Forbidden
  • Not authorized
  • Account inactive
  • Account over queries per second limit
  • Account over rate limit
  • Rate limit exceeded
404 Not Found: the requested resource could not be found, but it may be available again in the future.
405 Method Not Allowed: the client used a HTTP method other than GET or POST.
408 Request timeout.
414 Requested uri is too long.
415 Unsupported Media Type.
500 An error occurred while processing the request. Please try again later.
502 Internal network connectivity issue.
503 Service currently unavailable.
504 Internal network connectivity issue or a request that has taken too long to complete.
596 Service not found.