Calculate Route

Service version: 2
Last edit: 2024.06.04
TomTom Orbis Maps

Important notes:

Purpose

The Calculate Route service calculates a route between an origin and a destination, passing through waypoints if they are specified.

  • The route will take into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.
  • Information returned includes the distance, estimated travel time, and a representation of the route geometry.

Run this endpoint

You can easily run this endpoint. Go to the TomTom Routing API Playground page and follow the directions.

Request data

HTTPS method: GET   POST

Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Generic request format

get
Generic request example
1https://{baseURL}/maps/orbis/routing/calculateRoute/{routePlanningLocations}/{contentType}?key={Your_API_Key}
2&apiVersion={integer}
3&maxAlternatives={alternativeRoutes}
4&alternativeType={alternativeType}
5&minDeviationDistance={integer}
6&minDeviationTime={integer}
7&supportingPointIndexOfOrigin={integer}
8&vehicleHeading={integer}
9&sectionType={sectionType}
10&routeType={routeType}
11&traffic={traffic}
12&avoid={avoidType}
13&travelMode={travelMode}
14&vehicleEngineType={vehicleEngineType}
15&vehicleWeight={vehicleWeight}
16&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}
17&currentChargeInkWh={float}
18&maxChargeInkWh={float}
19&accelerationEfficiency={float}
20&decelerationEfficiency={float}
21&uphillEfficiency={float}
22&downhillEfficiency={float}
23&consumptionInkWhPerkmAltitudeGain={float}
24&recuperationInkWhPerkmAltitudeLoss={float}
25&auxiliaryPowerInkW={float}
26&extendedRouteRepresentation={extendedRouteRepresentation}

GET URL example

Note: Linebreaks are designated by "\".

get
Request URL example
1https://api.tomtom.com/maps/orbis/routing/calculateRoute/\
252.50931,13.42936:52.50274,13.43872/json?\
3&vehicleHeading=90&sectionType=traffic\
4&routeType=efficient&traffic=live&avoid=unpavedRoads\
5&travelMode=car&vehicleEngineType=combustion\
6&key={Your_API_Key}

GET curl command example

Note: Linebreaks are designated by "\".

get
Request curl command example
1curl -X GET '"https://api.tomtom.com/maps/orbis/routing/calculateRoute/\
252.50931,13.42936:52.50274,13.43872/json?\
3vehicleHeading=90\
4&sectionType=traffic\
5&routeType=efficient&traffic=live&avoid=unpavedRoads\
6&travelMode=car&vehicleEngineType=combustion\
7&key={Your_API_Key}" -H "accept:*/*" -H "TomTom-Api-Version:2"'
post
POST request URL example
https://api.tomtom.com/maps/orbis/routing/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?apiVersion=2&key={Your_API_Key}
post
POST request curl command example
1curl -X POST "https://api.tomtom.com/maps/orbis/routing/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?key={Your_API_Key}" -H "Content-type:application/json" -H "TomTom-Api-Version:2" -d \
2'{
3 "supportingPoints": [
4 {
5 "latitude": 52.5093,
6 "longitude": 13.42936
7 },
8 {
9 "latitude": 52.50844,
10 "longitude": 13.42859
11 }
12 ]
13}'

Types

The following data table describes the types that can be used in the Calculate Route service.

Type

Description

location string

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

point object

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}

dateTime string

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

ElectricConstantSpeedConsumptionPair
string (contains a pair of two, comma-separated floats)

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

Request headers

The following data table describes supported HTTP request headers.

  • Required headers must be used or the call will fail.
  • Optional headers may be used.
  • The order of request headers is not important.

Optional headers

Description

TomTom-Api-Version

Specifies API version
Value: 2

Note: this header is required if the query parameter apiVersion is not provided.

Accept-Encoding

Requests that the response be compressed. Value: gzip

Content-Encoding

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

Note: This header is optional and can only be used for POST requests.

Values:

  • identity
  • gzip
Content-Type

Specifies the MIME type of the body of the request.

Note: This header is required for POST requests.

Value: 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.

Base path parameters

The following table describes the parameters that can be used in the Calculate Route service.

  • Required parameters must be used or the call will fail.
  • The order of the required parameters is important and must be followed.
  • There are no optional parameters.

Required parameters (Base path)

Description

routePlanningLocations
string

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 locations (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.

Values: Colon-delimited locations, with the constraints mentionned above.

baseURL string

Base URL for calling the API.
Value: api.tomtom.com (The default global API endpoint.)

contentType string

The content type of the response structure. Only possible value:

  • json

Request parameters

The following table describes the parameters that can be used in the Calculate Route service.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of the optional request parameters is not important.

Required parameters

Description

key
string

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

apiVersion
integer

Specifies the API version.
Only allowed value: 2

Note: This parameter is not required if the header TomTom-Api-Version is provided.

Optional parameters

Description

maxAlternatives
integer

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

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

  • 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

alternativeType
string

When maxAlternatives is greater than 0, allows to specify the objective of computing alternative routes: finding routes that are significantly different than 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). 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

minDeviationDistance
integer

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.
Default value:0

minDeviationTime
integer

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.
Default value:0

supportingPointIndexOfOrigin
integer

Largest index in the array of supportingPoints per route or in joined arrays of supportingPoints per leg (see the POST data parameters section) for which supportingPoints[supportingPointIndexOfOrigin] lies on or before the origin point.
The Routing API uses this index as a hint to disambiguate situations where the supportingPoints 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.

Minimum value: 0
Maximum value: Size of supportingPoints array - 1

vehicleHeading
integer

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

sectionType
string

Specifies which of the section types is reported in the route response. sectionType can be specified multiple times (e.g., ...&sectionType=ferry&sectionType=traffic&...).
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.

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

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

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

extendedRouteRepresentation
string

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&... ). 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.

Values:
  • distance
  • travelTime
  • consumption

traffic string

Decides how traffic is considered for computing routes.
Possible values are:

  • live: In addition to historical travel times, routing and estimated travel time consider traffic jams and short- and long-term closures during the travel time window.

  • historical: Routing and estimated travel time consider historical travel times and long term closures. Traffic jams and short-term closures during the travel time window do not influence routing or travel time.

Default value: live

avoid
string

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.

routeType
string

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

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

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

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

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

Default value: fast

travelMode
string

Default value and only allowed value: car.

vehicleEngineType
string

The engine type of the vehicle. When the value is electric a detailed consumption model can be used.
Default value: combustion
Other value: electric

vehicleWeight
integer

Weight of the vehicle in kilograms.
When the value is positive then the calculated route respects weight restrictions.
It must be positive when used in the context of the detailed consumption model.
Default value: 0
Minimum value: 0

The Electric Consumption model

The route calculation uses the electric consumption model when the vehicleEngineType is set to electric and the constantSpeedConsumptionInkWhPerHundredkm is specified.

When the electric consumption model is used, then the response additionally contains batteryConsumptionInkWh in the route and leg summaries. When used together with the routeType value efficient, then route planning takes into account the consumption model.

The following data table 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 may be used.
  • The order of parameters in a request is not important.

Required parameters

Description

constantSpeedConsumptionInkWhPerHundredkm
Colon-delimited list of ElectricConstantSpeedConsumptionPair

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.

  • Otherwise, by linear extrapolation 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

Optional parameters

Description

currentChargeInkWh
float

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

maxChargeInkWh
float

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

auxiliaryPowerInkW
float

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
Default value: 0.0

accelerationEfficiency
float

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.
  • Requires vehicleWeight to be set.

Minimum value: 0.0
Maximum value: 1/decelerationEfficiency

decelerationEfficiency
float

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.

  • Requires vehicleWeight to be set.

Minimum value: 0.0
Maximum value: 1/accelerationEfficiency

uphillEfficiency
float

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.

  • Requires vehicleWeight to be set.

Minimum value: 0.0
Maximum value: 1/downhillEfficiency

downhillEfficiency
float

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.

  • Requires vehicleWeight to be set.

Minimum value: 0.0
Maximum value: 1/uphillEfficiency

consumptionInkWhPerkmAltitudeGain
float

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

recuperationInkWhPerkmAltitudeLoss
float

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

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

To give the feeling of the magnitudes of reasonable parameter values, the following data table provides an example of sensible values.

Parameter

Sensible values for the electric consumption model

constantSpeedConsumptionInkWhPerHundredkm50,8.2:130,21.3
vehicleWeight1900
currentChargeInkWh43
maxChargeInkWh85
auxiliaryPowerInkW1.7
accelerationEfficiency0.66
decelerationEfficiency0.91
uphillEfficiency0.74
downhillEfficiency0.73
consumptionInkWhPerkmAltitudeGain7.0
recuperationInkWhPerkmAltitudeLoss3.8

POST data parameters

The supportingPoints field is used to reconstruct a route. This route is then used as a reference route for route reassessment, or calculating zero or more alternative routes.

  • There are two options how to pass supportingPoints: for the entire route or per leg.
  • The provided sequence of supporting points is used as input for route reconstruction.
  • The pointWaypoints field is used to represent waypoints when reconstructing a route.
  • If supportingPointIndexOfOrigin is not used, and both minDeviationDistance and minDeviationTime are set to zero, then these origin and destination points are expected to be at (or very near) the beginning and end of the reference route, respectively.

Using supportingPointIndexOfOrigin, or setting at least one of minDeviationDistance or minDeviationTime to a value greater than zero, has the following consequences:

  • The origin point of the calculateRoute request must be on (or very near) the input reference route.
    • If this is not the case, an error is returned.
    • However, the origin point does not need to be at the beginning of the input reference route (it can be thought of as the current vehicle position on the reference route).
    • If used, supportingPointIndexOfOrigin must precisely indicate the location of the origin point in relation to the supportingPoints.
  • The reference route, returned as the first route in the calculateRoute response, will start at the origin point specified in the calculateRoute request. The initial part of the input reference route up until the origin point will be excluded from the response.
  • The values of minDeviationDistance and minDeviationTime determine how far alternative routes will be guaranteed to follow the reference route from the origin point onwards.
  • The vehicleHeading is ignored.

The following table describes the parameters that can be used in the Calculate Route service.

Parameter

Description

avoidAreas

object

Defines areas of certain shapes to avoid when planning routes. Supported shapes include rectangles. It can contain one of each supported shapes fields.

rectangles

array

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.

southWestCorner

object

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.

northEastCorner

object

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.

supportingPoints
array of point objects

Locations to be used as input for route reconstruction.

pointWaypoints

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

  • If specified, the array must not be empty.

pointWaypoint

Must contain one waypointSourceType and one supportingPointIndex object.

waypointSourceType

string

Denotes the source of the waypoint. Possible values:

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

supportingPointIndex

integer

An index into the supportingPoints array that denotes the location of the waypoint on the reference route.

  • Must be inside supportingPoints array boundaries.

legs
array

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.
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: fast

  • 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, respectively. It must be omitted if not needed.

RouteStop

Optinal parameters

Description

pauseTimeInSeconds
integer

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

Request content example

post
Request content example
1{
2 "avoidAreas": {
3 "rectangles": [
4 {
5 "southWestCorner": {
6 "latitude": 48.81851,
7 "longitude": 2.26593
8 },
9 "northEastCorner": {
10 "latitude": 48.90309,
11 "longitude": 2.41115
12 }
13 }
14 ]
15 },
16 "supportingPoints": [
17 {"latitude": 52.50930, "longitude": 13.42936},
18 {"latitude": 52.50844, "longitude": 13.42859},
19 {"latitude": 52.50601, "longitude": 13.42742}
20 ],
21 "pointWaypoints": [
22 {
23 "waypointSourceType": "USER_DEFINED",
24 "supportingPointIndex": 0
25 },
26 {
27 "waypointSourceType": "USER_DEFINED",
28 "supportingPointIndex": 1
29 }
30 ],
31 "legs": [
32 {
33 "routeType": "efficient",
34 "routeStop": {
35 "pauseTimeInSeconds": 610
36 }
37 },
38 {
39 "supportingPoints": [
40 {
41 "latitude": 52.5093,
42 "longitude": 13.42936
43 },
44 {
45 "latitude": 52.50844,
46 "longitude": 13.42859
47 }
48 ]
49 },
50 {
51 "routeType": "short"
52 }
53 ]
54}

Response data

Response headers

The following table describes the possible HTTP response headers.

Header

Description

Access-Control-Expose-Headers

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

Access-Control-Allow-Origin

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

Content-Encoding

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

Content-Type

The format of the response.
Value: application/json; 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. It is supported by HTTP/1.1 clients. It may not be supported by HTTP/1.0 clients.
Values:

  • 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. It is supported by HTTP/1.0 client. Value: no-cache

Tracking-ID

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.

Warning

This may be sent for deprecated features.

Response codes

The following table describes the possible HTTP response codes.

Code

Meaning & 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.

  • 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

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: The client took too long to transmit the request.

414

Requested uri is too long.

415

Unsupported Media Type.

429

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

500

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.

502

Internal network connectivity issue.

503

Service currently unavailable.

504

Internal network connectivity issue.

596

Service not found.

Example of a successful response

The routes in a successful response are listed in the order of decreasing optimality. In case the request includes the supporting points supportingPoints field, the response will specify the reconstructed route before any alternative routes.

Note: for the purpose of brevity the following example contains all the fields described in this document. In practice some fields are incompatible with others, and only a subset of them will be present in the response depending on the given request parameters.

A response could look like this: (Note: Comments are contained within ... ....)

Response body - JSON
1{
2 "formatVersion": "0.0.12",
3 "routes": [
4 {
5 "summary": {
6 "lengthInMeters": 1147,
7 "travelTimeInSeconds": 161,
8 "trafficDelayInSeconds": 15,
9 "trafficLengthInMeters": 147,
10 "departureTime": "2015-04-02T15:01:57+02:00",
11 "arrivalTime": "2015-04-02T15:04:38+02:00",
12 "batteryConsumptionInkWh": 0.155
13 },
14 "legs": [
15 {
16 "summary": {
17 "lengthInMeters": 108,
18 "travelTimeInSeconds": 11,
19 "trafficDelayInSeconds": 0,
20 "trafficLengthInMeters": 0,
21 "departureTime": "2015-04-02T15:01:57+02:00",
22 "arrivalTime": "2015-04-02T15:02:07+02:00",
23 "batteryConsumptionInkWh": 0.1,
24 "originalWaypointIndexAtEndOfLeg": 0,
25 "userDefinedPauseTimeInSeconds": 1020
26 },
27 "points": [
28 {
29 "latitude": 52.50931,
30 "longitude": 13.42937
31 },
32 {
33 "latitude": 52.50904,
34 "longitude": 13.42912
35 },
36 ...further points...
37 ]
38 },
39 ...further legs...
40 ],
41 "progress": [
42 {
43 "pointIndex": 0,
44 "travelTimeInSeconds": 0,
45 "distanceInMeters": 0,
46 "batteryConsumptionInkWh": 0
47 },
48 {
49 "pointIndex": 5,
50 "travelTimeInSeconds": 7,
51 "distanceInMeters": 74,
52 "batteryConsumptionInkWh": 0.002
53 },
54 ...further progresses...
55 {
56 "pointIndex": 87,
57 "travelTimeInSeconds": 161,
58 "distanceInMeters": 1147,
59 "batteryConsumptionInkWh": 0.155
60 }
61 ],
62 "sections": [
63 {
64 "startPointIndex": 0,
65 "endPointIndex": 3,
66 "sectionType": "TRAVEL_MODE"
67 "travelMode": "other"
68 },
69 {
70 "startPointIndex": 3,
71 "endPointIndex": 7,
72 "sectionType": "TRAVEL_MODE"
73 "travelMode": "car"
74 },
75 {
76 "startPointIndex": 2,
77 "endPointIndex": 5,
78 "sectionType": "TOLL"
79 },
80 {
81 "startPointIndex": 3,
82 "endPointIndex": 4,
83 "sectionType": "TUNNEL"
84 },
85 {
86 "startPointIndex": 0,
87 "endPointIndex": 1,
88 "sectionType": "PEDESTRIAN"
89 },
90 {
91 "startPointIndex": 3,
92 "endPointIndex": 4,
93 "sectionType": "TRAFFIC",
94 "simpleCategory": "JAM",
95 "effectiveSpeedInKmh": 40,
96 "delayInSeconds": 158,
97 "magnitudeOfDelay": 1,
98 "tec": {
99 "effectCode": 4,
100 "causes": [
101 {
102 "mainCauseCode": 1
103 },
104 {
105 "mainCauseCode": 26,
106 "subCauseCode": 2
107 }
108 ]
109 }
110 },
111 ...further sections...
112 ]
113 }
114 ...further routes...
115 ]
116}

Example of an error response

If an error occurs, the response contains the description of the error. The error response would look like this:

Error response example - JSON
1{
2 "formatVersion": "0.0.12",
3 "detailedError": {
4 "code": <error code>,
5 "message": "Error message"
6 }
7}

Structure of a successful response

Note that some names are implicitly defined. One example is the name leg when describing legs as an array of leg objects.

JSON field

Description

formatVersion

string

The format version.

routes
array of route objects

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.

summary
summary object

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.

legs
array of leg objects

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

  • Contains the summary and points fields.

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

points
array of objects

Each object in the array is a location on the surface of the globe defined by its latitude and longitude fields.

sections
array of section objects

Included if requested using the sectionType parameter. This array is available inside route objects.

  • Contains one or more section objects.

  • The structure of section objects is given below.

startPointIndex
number

Index of the first point (offset 0) in the route this section applies to.

endPointIndex
number

Index of the last point (offset 0) in the route this section applies to.

countryCode
string

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

simpleCategory
string

Type of the incident.

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

  • See the tec field for detailed information.

effectiveSpeedInKmh
number

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

delayInSeconds
number

The delay in seconds caused by the incident.

magnitudeOfDelay
number

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

tec
object

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.

effectCode
number

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.

causes
array of objects

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

  • It can contain the mainCauseCode and subCauseCode fields.

  • It can be used to define iconography and descriptions.

mainCauseCode
number

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.

subCauseCode
number

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.

lengthInMeters
number

The route or leg length in meters.

travelTimeInSeconds
number

The estimated travel time in seconds depending on traffic.

  • If traffic=historical, then travelTimeInSeconds includes historical travel times on the route.

  • If traffic=live, then travelTimeInSeconds includes historical travel times as well as traffic jams during the travel time window on the route.

trafficDelayInSeconds
number

The delay in seconds compared to free-flow conditions according to real-time traffic information. Note that this is zero if traffic=historical.

trafficLengthInMeters
number

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

deviationDistance
number

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.

deviationTime
number

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.

deviationPoint
object

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.

departureTime
string

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

arrivalTime
string

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

planningReason
string

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 criterion (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.

batteryConsumptionInkWh
number

The estimated electric energy consumption in kilowatt hours (kWh).

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

progress
array of progress point objects

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.

originalWaypointIndexAtEndOfLeg
number

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.

userDefinedPauseTimeInSeconds
number

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

Structure of the section object

Each section object contains additional information about parts of a route. A section object contains at least the fields startPointIndex, endPointIndex, and sectionType.

JSON field

Description

sectionType
string

Contains the response section type.

Request section typeResponse section type
carTrainCAR_TRAIN
countryCOUNTRY
ferryFERRY
motorwayMOTORWAY
pedestrianPEDESTRIAN
tollTOLL
trafficTRAFFIC
travelModeTRAVEL_MODE
tunnelTUNNEL
carpoolCARPOOL
urbanURBAN
unpavedUNPAVED
lowEmissionZoneLOW_EMISSION_ZONE
speedLimitSPEED_LIMIT
  • 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.

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

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

travelMode
string

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.

Structure of an error response

JSON field

Description

detailedError

object

This object provides a representation of the error message. It contains a code and a message field.

JSON field

Description
code

string

The (non-complete) list of error codes is:

Error code

Description
MAP_MATCHING_FAILURE

One of the input points (Origin, Destination, Waypoints) could not be matched to the map because there is no known drivable section near this point. This error code is always followed by a description of one point that was not matchable:

  • Origin (Latitude, Longitude)

  • Destination (Latitude, Longitude)

  • Waypoint N (Latitude, Longitude)

NO_ROUTE_FOUND

No valid route could be found.

CANNOT_RESTORE_BASEROUTE

The route reconstruction using supportingPoints failed.

BAD_INPUT

Some input parameter combination was not valid.

COMPUTE_TIME_LIMIT_EXCEEDED

The request exceeded the internal compute time limit and was canceled.

message string

A human readable error message.

  • It is a freeform string which may be extended in the future, so it is recommended to only match substrings of the description.

  • The string always contains an error code.

Example of a description string:

Engine error while executing route request: MAP_MATCHING_FAILURE: Origin (54.3226, 3.11463)

Engine error while executing route request: MAP_MATCHING_FAILURE: Origin (54.3226, 3.11463)

Engine error while executing route request: MAP_MATCHING_FAILURE: Waypoint 3 (54.3226, 3.11463)