Calculate Route

Service version: 1

Last edit: 2022.02.25

Deprecation Notices

Nov 1, 2020
The error response element is deprecated and replaced by detailedError
Until its deprecation, both fields are sent in error responses.
The message field in detailedError contains the same string as the description field in error.
The error response element will be withdrawn following a 12 month deprecation period.
The planned withdrawal date is Dec 1, 2021.
Following withdrawal, error responses will no longer contain the error field (or its subfields).

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.
Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer 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

The following request URL contains all of this endpoint's respective parameters. For their details, please see the Common Routing Parameters page.

GET

Request example

1https://{baseURL}/routing/{versionNumber}/calculateRoute/{routePlanningLocations}/{contentType}?key={Your_API_Key}
2&callback={callback}
3&maxAlternatives={alternativeRoutes}
4&alternativeType={alternativeType}
5&minDeviationDistance={integer}
6&minDeviationTime={integer}
7&instructionsType={instructionsType}
8&language={language}
9&computeBestOrder={boolean}
10&routeRepresentation={routeRepresentation}
11&computeTravelTimeFor={trafficTypes}
12&vehicleHeading={integer}
13&sectionType={sectionType}
14&report={effectiveSettings}
15&departAt={time}
16&arriveAt={time}
17&routeType={routeType}
18&traffic={boolean}
19&avoid={avoidType}
20&travelMode={travelMode}
21&hilliness={hilliness}
22&windingness={windingness}
23&vehicleMaxSpeed={vehicleMaxSpeed}
24&vehicleWeight={vehicleWeight}
25&vehicleAxleWeight={vehicleAxleWeight}
26&vehicleLength={vehicleLength}
27&vehicleWidth={vehicleWidth}
28&vehicleHeight={vehicleHeight}
29&vehicleCommercial={boolean}
30&vehicleLoadType={vehicleLoadType}
31&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}
32&vehicleEngineType={vehicleEngineType}
33&constantSpeedConsumptionInLitersPerHundredkm={CombustionConstantSpeedConsumptionPairs}
34&currentFuelInLiters={float}
35&auxiliaryPowerInLitersPerHour={float}
36&fuelEnergyDensityInMJoulesPerLiter={float}
37&accelerationEfficiency={float}
38&decelerationEfficiency={float}
39&uphillEfficiency={float}
40&downhillEfficiency={float}
41&consumptionInkWhPerkmAltitudeGain={float}
42&recuperationInkWhPerkmAltitudeLoss={float}
43&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}
44&currentChargeInkWh={float}
45&maxChargeInkWh={float}
46&auxiliaryPowerInkW={float}
47&chargeMarginsInkWh={commaSeparatedFloats}

GET URL example

Note: Linebreaks are designated by "\".

GET

Request URL example

1https://api.tomtom.com/routing/1/calculateRoute/\
252.50931,13.42936:52.50274,13.43872/json?\
3instructionsType=text&language=en-US\
4&vehicleHeading=90&sectionType=traffic\
5&report=effectiveSettings&routeType=eco\
6&traffic=true&avoid=unpavedRoads\
7&travelMode=car&vehicleMaxSpeed=120\
8&vehicleCommercial=false&vehicleEngineType=combustion\
9&key={Your_API_Key}

GET curl command

Note: Linebreaks are designated by "\".

GET

Request curl command

1curl -X GET '"https://api.tomtom.com/routing/1/calculateRoute/\
252.50931,13.42936:52.50274,13.43872/json?\
3instructionsType=text&language=en-US&vehicleHeading=90\
4&sectionType=traffic&report=effectiveSettings\
5&routeType=eco&traffic=true&avoid=unpavedRoads\
6&travelMode=car&vehicleMaxSpeed=120&vehicleCommercial=false\
7&vehicleEngineType=combustion&key={Your_API_Key}" -H "accept:*/*"'

POST URL example

POST

Request URL example

https://api.tomtom.com/routing/1/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?key={Your_API_Key}

POST curl command

POST

Request curl command

1curl -X POST "https://api.tomtom.com/routing/1/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?key={Your_API_Key}" -H "Content-type:application/json" -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  "avoidVignette": [
14    "AUS",
15    "CHE"
16  ]
17}'

Types

The following data table describes a subset of the types that can be used in the Calculate Route service; the remaining types are listed on the Common Routing Parameters page.

Type	Description
`circle`	A circle with a center point and a radius (in meters). The radius must be a positive integer with the maximum value of 135000. Example: `circle(52.37245,4.89406,10000)`
`generalizedLocation`	A `location` or a `circle`. Examples: `52.37245,4.89406` `circle(52.37245,4.89406,10000)`
`commaSeparatedFloats`	Comma-separated list of floats. Example: `1.23,0`
`point`	To be used in the POST data only. Please refer to the Common Routing Parameters page.

Request headers

There currently are no additional headers specific to the Calculate Route service. The common headers are listed on the Common Routing Parameters page.

Base path parameters

The following table describes a subset of the parameters that can be used in the Calculate Route service. The remaining parameters are listed on the Common Routing Parameters page.

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

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

Required parameters (Base path)	Description
`versionNumber` integer	The service version number. Value: The current value is `1`.
`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 `generalizedLocation`s (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, a waypoint of type `circle` does not. Circle waypoints cannot be used when `computeBestOrder` is `true`. Values: Colon-delimited `generalizedLocation`s, with the constraints mentionned above.

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 generalizedLocations (known as waypoints in this context) may be provided:
- The maximum allowed number of waypoints is 150.
- A waypoint of type location results in an extra leg in the response, a waypoint of type circle does not.
- Circle waypoints cannot be used when computeBestOrder is true.

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

Request parameters

The following table describes a subset of the parameters that can be used in the Calculate Route service; the remaining parameters are listed on the Common Routing Parameters page.

There are no required parameters. All of the following parameters are optional.
The order of these optional request parameters is not important.

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. Using a value greater than `0` in conjunction with `computeBestOrder` set to `true` is not allowed. Fewer alternative routes may be returned if either fewer alternatives exist, or the requested number of alternatives is larger than the service can calculate. Default value: `0` Maximum value: `5`
`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: This optional parameter can only be used when reconstructing a route. Default value: `anyRoute` Other values: `betterRoute`
`minDeviationDistance` integer	All alternative routes returned will follow the reference route (see the POST requests section) from the origin point of the `calculateRoute` request for at least this number of meters. Can only be used when reconstructing a route. The `minDeviationDistance` parameter cannot be used in conjunction with `arriveAt`. Default value: `0`
`minDeviationTime` integer	All alternative routes returned will follow the reference route (see the POST requests section) from the origin point of the `calculateRoute` request for at least this number of seconds. Can only be used when reconstructing a route. The `minDeviationTime` parameter cannot be used in conjunction with `arriveAt`. Default value: `0`
`instructionsType` string	If specified, guidance instructions will be returned (if available). Possible values are: `coded`: returns raw instruction data without human-readable messages. `text`: returns raw instructions data with human-readable messages in plain text. `tagged`: returns raw instruction data with tagged human-readable messages to permit formatting. Note: The `instructionsType` parameter cannot be used in conjunction with `routeRepresentation=none`. If alternative routes are requested, instructions will be generated for each route returned. See the Tagged messages section for more information about tagged messages. Values: `coded` `text` `tagged`
`language` string	The `language` parameter determines the language of the guidance messages. Proper nouns (the names of streets, plazas, etc.) are returned in the specified language, or if that is not available, they are returned in an available language that is close to it. Allowed values are (a subset of) the IETF language tags described here. The currently supported languages are listed in the Supported languages section. Default value: `en-GB`
`computeBestOrder` boolean	Re-orders the route waypoints with a fast heuristic algorithm to reduce the overall route length. Note that based on the heuristic nature of the algorithm, optimality is not guaranteed. Yields best results when used in conjunction with `routeType` shortest. Possible boolean values are: `true` (compute a better order, if possible; not allowed to be used in conjunction with maxAlternatives value greater than `0`; not allowed to be used in conjunction with circle waypoints). The response will include the reordered waypoint indices in the field `optimizedWaypoints`. `false` (use the locations in the given order). Not allowed to be used in conjunction with `routeRepresentation=none`. Default value: `false`
`routeRepresentation` string	Specifies the representation of the set of routes provided as a response. Possible values are: `polyline`: includes routes in the response. `summaryOnly`: as per `polyline`, but excluding the `points` elements for the routes in the response. `none`: only includes the optimized waypoint indices but does not include the routes in the response. This parameter value can only be used in conjunction with `computeBestOrder=true`. Default value: `polyline` Other values: `summaryOnly` `none`
`computeTravelTimeFor` string	Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time. Possible values are: `none`: do not compute additional travel times. `all`: compute travel times for all types of traffic information, specifying all results in the fields: `noTrafficTravelTimeInSeconds` `historicTrafficTravelTimeInSeconds` `liveTrafficIncidentsTravelTimeInSeconds` being included in the summaries in the route response. Default value: `none` Other value: `all`
`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=tollRoads&sectionType=tollVignettes&...`). Possible values are: `carTrain`: sections of the route that are car trains. `ferry`: sections of the route that are ferries. `tunnel`: sections of the route that are tunnels. `motorway`: sections of the route that are motorways. `pedestrian`: sections of the route that are only suited for pedestrians. `tollRoad`: sections of the route that require a toll to be payed. `tollVignette`: sections of the route that require a toll vignette to be present. `country`: sections indicating which countries the route is in. `travelMode`: sections in relation to the request parameter `travelMode`. `traffic`: sections of the route that contain traffic information. `carpool`: sections of the route that require use of carpool (HOV/High Occupancy Vehicle) lanes. `urban`: sections of the route that are located within urban areas. Default value: `travelMode` Other values: `carTrain` `country` `ferry` `motorway` `pedestrian` `tollRoad` `tollVignette` `traffic` `tunnel` `carpool` `urban`
`chargeMarginsInkWh` `commaSeparatedFloats`	Specifies a list of margins in kilowatt-hours (kWh) for computing `reachableRouteOffsets`. Can only be used when all of `constantSpeedConsumptionInkWhPerHundredkm`, `maxChargeInkWh`, and `currentChargeInkWh` are specified. The items in the list must be in strictly decreasing order. The list is restricted to exactly one item. Minimum value: `0` Maximum value: `0`

Further parameters not contained in the preceding table can be specified. A complete list is located in the Common Routing Parameters page. This page also includes the parameters used to define a detailed vehicle consumption model.

Using the detailed consumption model has two consequences for a calculateRoute request:

When the parameter routeType is set to eco, then the Consumption Model will be taken into account for route planning.
When constantSpeedConsumption* is specified, the response will include either fuelConsumptionInLiters or batteryConsumptionInkWh (for vehicleEngineType set to combustion or electric, respectively) as an additional field in each summary element.

POST data parameters

The supportingPoints field is used for reconstructing a route and for calculating zero or more alternative routes to this reference route.

The provided sequence of supporting points is used as input for route reconstruction.
The alternative routes are calculated between the origin and destination points specified in the base path parameter locations.
If 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.
Intermediate locations (waypoints) are not supported when using supportingPoints.
The reference route may contain traffic incidents of type ROAD_CLOSURE, which are ignored for the calculation of the reference route's travel time and traffic delay.

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).
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 route must use departAt.
The vehicleHeading is ignored.

The following table describes a subset of the parameters that can be used in the Calculate Route service; the remaining parameters are listed on the Common Routing Parameters page.

Parameter Description

supportingPoints An array of point objects, to be used as input for route reconstruction.

reassessmentParameterSets An array of reassessmentParameterSet objects, to be used as input for route reassessment.
Route reassessment provides information on how some properties of the route would be different with different input values.
(Note that reassessment does not affect the shape of the route.)
For example, route reassessment can be used to quantify the impact of air conditioning use on total power consumption.
If specified, the array must contain exactly one entry.
A reassessmentParameterSet object is a set of parameters used together to reassess the planned route.
Such an object must contain at least one parameter; currently the only supported parameter is auxiliaryPowerInkW.

Parameter	Description
`supportingPoints`	An array of `point` objects, to be used as input for route reconstruction.
`reassessmentParameterSets`	An array of `reassessmentParameterSet` objects, to be used as input for route reassessment. Route reassessment provides information on how some properties of the route would be different with different input values. (Note that reassessment does not affect the shape of the route.) For example, route reassessment can be used to quantify the impact of air conditioning use on total power consumption. If specified, the array must contain exactly one entry. A `reassessmentParameterSet` object is a set of parameters used together to reassess the planned route. Such an object must contain at least one parameter; currently the only supported parameter is `auxiliaryPowerInkW`.

Request content example

POST

Request example

1{
2  "supportingPoints": [
3    {"latitude": 52.50930, "longitude": 13.42936},
4    {"latitude": 52.50844, "longitude": 13.42859}
5  ],
6  "avoidVignette": [
7    "AUS",
8    "CHE"
9  ],
10  "reassessmentParameterSets": [
11    {
12      "auxiliaryPowerInkW": 0.3
13    }
14  ]
15}

Response data

Response headers

There currently are no additional response headers specific to the Calculate Route service; the common response headers are listed on the Common Routing Parameters page.

Response codes

There currently are no additional response codes specific to the Calculate Route service; the common response codes are listed on the Common Routing Parameters page.

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.

In the following response example, note that the fields deviationDistance, deviationTime, and deviationPoint cannot occur if there is more than one leg. This is because because waypoints and supporting points are mutually exclusive.

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

Response body

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        "noTrafficTravelTimeInSeconds": 120,
13        "historicTrafficTravelTimeInSeconds": 157,
14        "liveTrafficIncidentsTravelTimeInSeconds": 161,
15        "batteryConsumptionInkWh": 0.155,
16        "deviationDistance": 1735,
17        "deviationTime": 127,
18        "deviationPoint": {
19          "latitude": 52.50904,
20          "longitude": 13.42912
21        },
22        "reachableRouteOffsets": [
23          {
24            "chargeMarginInkWh": 0.0,
25            "routeOffsetInMeters": 1147,
26            "point": {
27              "latitude": 52.51565,
28              "longitude": 13.43979
29            },
30            "pointIndex": 50
31          }
32        ]
33      },
34      "routeReassessments": [
35        {
36          "batteryConsumptionInkWh": 0.2,
37          "reachableRouteOffsets": [
38            {
39              "chargeMarginInkWh": 0.0,
40              "routeOffsetInMeters": 1147,
41              "point": {
42                "latitude": 52.51565,
43                "longitude": 13.43979
44              },
45              "pointIndex": 50
46            }
47          ]
48        }
49      ],
50      "legs": [
51        {
52          "summary": {
53            "lengthInMeters": 108,
54            "travelTimeInSeconds": 11,
55            "trafficDelayInSeconds": 0,
56            "trafficLengthInMeters": 0,
57            "departureTime": "2015-04-02T15:01:57+02:00",
58            "arrivalTime": "2015-04-02T15:02:07+02:00",
59            "noTrafficTravelTimeInSeconds": 10,
60            "historicTrafficTravelTimeInSeconds": 11,
61            "liveTrafficIncidentsTravelTimeInSeconds": 11,
62            "batteryConsumptionInkWh": 0.1
63          },
64          "points": [
65            {
66              "latitude": 52.50931,
67              "longitude": 13.42937
68            },
69            {
70              "latitude": 52.50904,
71              "longitude": 13.42912
72            },
73  ...further points...
74          ]
75        },
76  ...further legs...
77      ],
78      "sections": [
79        {
80          "startPointIndex": 0,
81          "endPointIndex": 3,
82          "sectionType": "TRAVEL_MODE"
83          "travelMode": "other"
84        },
85        {
86          "startPointIndex": 3,
87          "endPointIndex": 7,
88          "sectionType": "TRAVEL_MODE"
89          "travelMode": "car"
90        },
91        {
92          "startPointIndex": 2,
93          "endPointIndex": 5,
94          "sectionType": "TOLL_ROAD"
95        },
96        {
97          "startPointIndex": 3,
98          "endPointIndex": 4,
99          "sectionType": "TUNNEL"
100        },
101        {
102          "startPointIndex": 0,
103          "endPointIndex": 1,
104          "sectionType": "PEDESTRIAN"
105        },
106        {
107          "startPointIndex": 3,
108          "endPointIndex": 4,
109          "sectionType": "TRAFFIC",
110          "simpleCategory": "JAM",
111          "effectiveSpeedInKmh": 40,
112          "delayInSeconds": 158,
113          "magnitudeOfDelay": 1,
114          "tec": {
115            "effectCode": 4,
116            "causes": [
117              {
118                "mainCauseCode": 1
119              },
120              {
121                "mainCauseCode": 26,
122                "subCauseCode": 2
123              }
124            ]
125          }
126        },
127  ...further sections...
128      ],
129      "guidance": {
130        "instructions": [
131          {
132            "routeOffsetInMeters": 0,
133            "travelTimeInSeconds": 0,
134            "point": {
135              "latitude": 52.50931,
136              "longitude": 13.42937
137            },
138            "pointIndex": 0,
139            "instructionType": "LOCATION_DEPARTURE",
140            "street": "An der Schillingbrücke",
141            "countryCode":"DEU",
142            "possibleCombineWithNext": false,
143            "drivingSide": "RIGHT",
144            "maneuver": "DEPART",
145            "message": "Leave from An der Schillingbrücke"
146          },
147  ...further instructions...
148        ],
149        "instructionGroups": [
150          {
151            "firstInstructionIndex": 0,
152            "lastInstructionIndex": 5,
153            "groupLengthInMeters": 4567,
154            "groupMessage": "Leave from An der Schillingbrücke and continue to A1/E35"
155          },
156  ...further instruction groups...
157        ]
158      }
159    }
160  ...further routes...
161  ],
162  "optimizedWaypoints": [
163    {
164      "providedIndex": 0,
165      "optimizedIndex": 1
166    },
167    {
168      "providedIndex": 1,
169      "optimizedIndex": 0
170    }
171  ...further optimized waypoints...
172  ],
173  "report": {
174    "effectiveSettings": [
175      {
176        "key": "avoid",
177        "value": "motorways"
178      },
179      {
180        "key": "computeBestOrder",
181        "value": "true"
182      },
183  ...further settings...
184    ]
185  }
186}

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

1{
2  "formatVersion": "0.0.12",
3  "error": {
4    "description": "Error description (same as detailedError["message"])"
5  },
6  "detailedError": {
7    "code": <error code>,
8    "message": "Error message"
9  }
10}

Special behaviour for content type jsonp (JSON with Padding)

When the contentType=jsonp is used, the returned HTTP status code is always OK (200).

This ensures that the jsonp callback will be invoked on the client side regardless of the outcome of the request.
In order to provide the client with the actual status of the request, a field called statusCode is added to the response body.

Currently, the preceding statement is not true for certain types of errors described below.

For those errors the HTTP status code is returned as normal (400, 500, ...) and the response content type is text/xml independent from the request content type.
For those errors, the content doesn't follow the documented format for error responses.
Note: This imperfection should not cause problems during normal use of the API.

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.
`routeReassessments` array of objects	Included if `reassessmentParameterSets` is specified. Each object in the array corresponds to the entry with the same index in`reassessmentParameterSets`(see the POST data parameters) and contains the results of a reassessment using the corresponding `reassessmentParameterSet`. The objects describe particular aspects of the route as a whole. Their values may differ from those reported in the`route` `summary`. If the`reassessmentParameterSet`contains`auxiliaryPowerInkW`, then the corresponding object may contain the following fields (see individual field descriptions for details): `batteryConsumptionInkWh` `reachableRouteOffsets` The objects in this array may be extended with new fields in the future; clients should ignore fields they do not recognize.
`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	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 (only included for a `routeRepresentation` `polyline`).
`endPointIndex` number	Index of the last point (offset `0`) in the route this section applies to (only included for a `routeRepresentation` `polyline`).
`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 `ty` of the Online Traffic Incident Details.
`tec` object	Details of the traffic event. It uses the definitions in the TPEG2-TEC standard. It can contain the`effectCode`and`causes`fields.
`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`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.
`subCauseCode` number	The subcause of the traffic event. Contains a value in the sub cause table defined by the `mainCauseCode`, as defined in the TPEG2-TEC standard.
`lengthInMeters` number	The route or leg length in meters.
`travelTimeInSeconds` number	The estimated travel time in seconds. Note that even when `traffic=false`, `travelTimeInSeconds` still includes the delay due to traffic.
`trafficDelayInSeconds` number	The delay in seconds compared to free-flow conditions according to real-time traffic information.
`trafficLengthInMeters` number	The portion of the route or leg, expressed in meters, that is affected by traffic events which cause the delay.
`noTrafficTravelTimeInSeconds` number	The estimated travel time in seconds calculated as if there are no delays on the route due to traffic conditions (e.g., congestion). Included if requested using the `computeTravelTimeFor` parameter.
`historicTrafficTravelTimeInSeconds` number	The estimated travel time in seconds calculated using time-dependent historic traffic data. Included if requested using the `computeTravelTimeFor` parameter.
`liveTrafficIncidentsTravelTimeInSeconds` number	The estimated travel time in seconds calculated using real-time speed data. Included if requested using the `computeTravelTimeFor` parameter.
`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)`routesummary`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)`routesummary`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)`routesummary`fields.
`fuelConsumptionInLiters` number	The estimated fuel consumption in liters using the Combustion Consumption Model. Included if: The `vehicleEngineType` is set to `combustion`. The `constantSpeedConsumptionInLitersPerHundredkm` is specified. The value will be non-negative (i.e., positive).
`batteryConsumptionInkWh` number	The estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model. Included if: `vehicleEngineType` is set to `electric`. `constantSpeedConsumptionInkWhPerHundredkm` is specified. The value of `batteryConsumptionInkWh` includes the recuperated electric energy and can therefore be negative (which indicates gaining energy). If both `maxChargeInkWh` and `currentChargeInkWh` are specified, recuperation will be capped to ensure that the battery charge level never exceeds `maxChargeInkWh`. If neither `maxChargeInkWh` nor `currentChargeInkWh` are specified, unconstrained recuperation is assumed in the consumption calculation.
`reachableRouteOffsets` array of objects	This field is included if `chargeMarginsInkWh` is specified. It is not present in the `leg` `summary` field. Each object in the array corresponds to an entry in `chargeMarginsInkWh`, and describes the reachable point on the route with respect to the charge margin specified there. Effectively, the farthest the vehicle can go on the route on its current charge, without depleting the battery beyond the specified margin. Objects in the array contain the following fields: `chargeMarginInkWh`: the charge margin this reachable point is calculated for. `point`: location of the reachable point defined as a latitude longitude pair. `pointIndex`: largest index in the polyline of the route for which `points[pointIndex]` lies on or before`point`. `routeOffsetInMeters`: the distance from the start of the route to the reachable point. Note that: If `currentChargeInkWh` is less than or equal to`chargeMarginInkWh`,`routeOffsetInMeters`is zero. `routeOffsetInMeters`is at most`lengthInMeters`.
`optimizedWaypoints` array of objects	A description of an optimized sequence of waypoints. It shows the index from the user-provided waypoint sequence for the original and optimized list. For instance, a response: 1{ 2 "optimizedWaypoints": [ 3 { 4 "providedIndex": 0, 5 "optimizedIndex": 1 6 }, 7 { 8 "providedIndex": 1, 9 "optimizedIndex": 2 10 }, 11 { 12 "providedIndex": 2, 13 "optimizedIndex": 0 14 } 15 ] 16} means that the original sequence is [0, 1, 2] and optimized sequence is [1, 2, 0]. Since the index starts by `0` the original is "first, second, third", while the optimized is "second, third, first".
`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`.
`guidance` object	This contains guidance related fields. This field is present only when guidance was requested and is available.
`instruction` object	A set of attributes describing a maneuver, e.g., "Turn right", "Keep left", "Take the ferry", "Take the motorway", "Arrive".
`instructionGroup` object	This groups a sequence of instruction elements which are related to each other. The sequence range is constrained with `firstInstructionIndex` and `lastInstructionIndex`. When human-readable text messages are requested for guidance (`instructionType=text` or `tagged`), then the `instructionGroup` has a summary message returned when available.
`effectiveSettings` array of objects	Each object in the array represents an effective parameter or a data used when calling the Calculate Route API. Each object has fields `key` and `value` both containing a string describing the input and its value.
`statusCode` number	The original HTTP status code as listed in the response codes (note: included for content type `jsonp` only).
`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 then the reference route, according to the given planning criteria (set by `routeType`). This field is included in the response only if the route is requested with `alternativeType=betterRoute`. This field is not present in the`legsummary`field.

Maneuver codes

The following table describes the possible values of the maneuver instruction field.

Maneuver value	Example translation
`ARRIVE`	You have arrived.
`ARRIVE_LEFT`	You have arrived. Your destination is on the left.
`ARRIVE_RIGHT`	You have arrived. Your destination is on the right.
`DEPART`	Leave.
`STRAIGHT`	Keep straight on.
`KEEP_RIGHT`	Keep right.
`BEAR_RIGHT`	Bear right.
`TURN_RIGHT`	Turn right.
`SHARP_RIGHT`	Turn sharp right.
`KEEP_LEFT`	Keep left.
`BEAR_LEFT`	Bear left.
`TURN_LEFT`	Turn left.
`SHARP_LEFT`	Turn sharp left.
`MAKE_UTURN`	Make a U-turn.
`ENTER_MOTORWAY`	Take the motorway.
`ENTER_FREEWAY`	Take the freeway.
`ENTER_HIGHWAY`	Take the highway.
`TAKE_EXIT`	Take the exit.
`MOTORWAY_EXIT_LEFT`	Take the left exit.
`MOTORWAY_EXIT_RIGHT`	Take the right exit.
`TAKE_FERRY`	Take the ferry.
`ROUNDABOUT_CROSS`	Cross the roundabout.
`ROUNDABOUT_RIGHT`	At the roundabout take the exit on the right.
`ROUNDABOUT_LEFT`	At the roundabout take the exit on the left.
`ROUNDABOUT_BACK`	Go around the roundabout.
`TRY_MAKE_UTURN`	Try to make a U-turn.
`FOLLOW`	Follow.
`SWITCH_PARALLEL_ROAD`	Switch to the parallel road.
`SWITCH_MAIN_ROAD`	Switch to the main road.
`ENTRANCE_RAMP`	Take the ramp.
`WAYPOINT_LEFT`	You have reached the waypoint. It is on the left.
`WAYPOINT_RIGHT`	You have reached the waypoint. It is on the right.
`WAYPOINT_REACHED`	You have reached the waypoint.

Structure of the `instruction` object

Guidance instruction deprecation policy
As part of the continuous improvement of the Routing API, we also extend our guidance instructions with new features.
In many cases, this requires the introduction of new maneuver codes for new types of instructions. Hence we cannot guarantee the same deprecation policy for guidance instructions as compared to the rest of the Routing API.
In particular, clients are expected to be forward compatible, and we reserve the right to extend all enums defined below with new values. This includes completely new maneuver codes for new types of instructions.
At the same time we reserve the right to retire enum values for instructions that are superseded by their improved counterparts no longer generated by the internal Guidance component. The same rules for forward-/backward-compatibility apply to fields for guidance instructions.
For the retirement of instructions that are no longer relevant, we give a deprecation period of 4 months. After this period we reserve the right to remove deprecated values at our convenience.

JSON field	Description
`routeOffsetInMeters` number	The distance from the start of the route to the point of the instruction.
`travelTimeInSeconds` number	The estimated travel time up to the point corresponding to `routeOffsetInMeters`.
`point` `point` object	Location of the maneuver. Example: A location of the maneuver 1"point":{ 2 "latitude":52.36965, 3 "longitude":4.70208 4}
`pointIndex` number	The index of the `point` in the array of polyline points. Equivalent to `startPointIndex` and `endPointIndex` in sections: Largest index in the polyline of the route for which `points[pointIndex]` lies on or before `point`. In particular you may assume that `point` lies on `points[pointIndex]` or on the route segment described by `points[pointIndex]` and `points[pointIndex+1]`.
`instructionType` string	The type of instruction, e.g., a turn or a change of road form. Possible values: `TURN` `ROAD_CHANGE` `LOCATION_DEPARTURE` `LOCATION_ARRIVAL` `DIRECTION_INFO` `LOCATION_WAYPOINT`
`roadNumbers` array of strings	This lists the road number of the next significant road segment after the maneuver, or of the road that has to be followed. Example: Aggregate "roadNumbers":["E34","N205"]
`exitNumber` string	A string telling the number(s) of a highway exit taken by the current maneuver. If an exit has multiple exit numbers, numbers will be separated by "," and possibly aggregated by "-", e.g., "10, 13-15".
`street` string	The street name of the next significant road segment after the maneuver, or of the street that should be followed.
`signpostText` string	The text on a signpost which is most relevant to the maneuver, or to the direction that should be followed.
`countryCode` string	The 3-character ISO 3166-1 alpha-3 country code.
`stateCode` string	A subdivision (e.g., state) of the country, represented by the second part of an ISO 3166-2 code. This is only available for some countries like the US, Canada, and Mexico.
`junctionType` string	The type of the junction where the maneuver takes place. For larger roundabouts, two separate instructions are generated for entering and leaving the roundabout. Possible values: `REGULAR` `ROUNDABOUT` `BIFURCATION`
`turnAngleInDecimalDegrees` number	Indicates the direction of an instruction. If `junctionType` indicates a turn instruction: `-180` = U-turn `[-179, -1]` = Left turn `0` = Straight on (a '0 degree' turn) `[1, 179]` = Right turn If `junctionType` indicates a bifurcation instruction: `<0` - keep left `>0` - keep right
`roundaboutExitNumber` number	This indicates which exit to take at a roundabout.
`possibleCombineWithNext` boolean	It is possible to optionally combine the instruction with the next one. This can be used to build messages like "Turn left and then turn right". Possible values: `true` `false`
`drivingSide` string	Indicates left-hand vs. right-hand side driving at the point of the maneuver. Possible values: `LEFT` `RIGHT`
`maneuver` string	A code identifying the maneuver (e.g., "Turn right"). See the following Maneuver codes section.
`message` string	A human-readable message for the maneuver.
`combinedMessage` string	A human-readable message for the maneuver combined with the message from the next instruction. See the following example of a combined message section.

Example of a combined message

Sometimes it is possible to combine two successive instructions into a single instruction making it easier to follow. When this is the case the possibleCombineWithNext flag will be true. For example:

possibleCombineWithNext flag set to true

10. Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam
11. Follow Einsteinweg/A10/E22 towards Ring Amsterdam

The possibleCombineWithNext flag on instruction 10 is true. This indicates to the clients of coded guidance that it can be combined with instruction 11. The instructions will be combined automatically for clients requesting human-readable guidance. The combinedMessage field contains the combined message:

combinedMessage field

Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam then follow Einsteinweg/A10/E22 towards Ring Amsterdam.

Tagged messages

A human-readable message is built up from repeatable identified elements. These are tagged to allow client applications to format them correctly. The following message components are tagged when instructionsType=tagged:

Message component	Tag
Street or road name	`street`
Road number	`roadNumber`
Signpost text	`signpostText`
Exit number - motorway	`exitNumber`
Exit number - roundabout	`roundaboutExitNumber`

Examples of tagged messages

Turn left message

Turn left onto <roadNumber>A4</roadNumber>/<roadNumber>E19</roadNumber> towards <signpostText>Den Haag</signpostText>

Take exit message

Take exit no. <exitNumber>1</exitNumber> onto <street>Anderlechtlaan</street> towards <signpostText>Amsterdam-Sloten</signpostText>

Follow message

Follow <street>Rijksweg A9</street>/<roadNumber>A9</roadNumber> towards <signpostText>Amstelveen</signpostText>

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 type	Response section type
`carTrain`	`CAR_TRAIN`
`country`	`COUNTRY`
`ferry`	`FERRY`
`motorway`	`MOTORWAY`
`pedestrian`	`PEDESTRIAN`
`tollRoad`	`TOLL_ROAD`
`tollVignette`	`TOLL_VIGNETTE`
`traffic`	`TRAFFIC`
`travelMode`	`TRAVEL_MODE`
`tunnel`	`TUNNEL`
`carpool`	`CARPOOL`
`urban`	`URBAN`

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 TOLL_VIGNETTE section additionally contains a countryCode since toll vignettes are often specific to a country.

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

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

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

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

error
string Deprecated
Legacy version of detailedError
The description field has the same content as the message field in detailedError.

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.

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)

statusCode
number The original HTTP status code as listed in response codes (included for content type jsonp only).

Supported languages

Language name	Language tag
Afrikaans (South Africa)	`af-ZA`
Arabic	`ar`
Bulgarian	`bg-BG`
Chinese (Taiwan)	`zh-TW`
Czech	`cs-CZ`
Danish	`da-DK`
Dutch	`nl-NL`
English (Great Britain)	`en-GB`
English (USA)	`en-US`
Finnish	`fi-FI`
French	`fr-FR`
German	`de-DE`
Greek	`el-GR`
Hungarian	`hu-HU`
Indonesian	`id-ID`
Italian	`it-IT`
Korean	`ko-KR`
Lithuanian	`lt-LT`
Malay	`ms-MY`
Norwegian	`nb-NO`
Polish	`pl-PL`
Portuguese (Brazil)	`pt-BR`
Portuguese (Portugal)	`pt-PT`
Russian	`ru-RU`
Slovak	`sk-SK`
Slovenian	`sl-SI`
Spanish (Castilian)	`es-ES`
Spanish (Mexico)	`es-MX`
Swedish	`sv-SE`
Thai	`th-TH`
Turkish	`tr-TR`

The following language code abbreviations are also supported:

Language name	Language tag	Inferred language tag
English	`en`	`en-GB`
French	`fr`	`fr-FR`
German	`de`	`de-DE`
Italian	`it`	`it-IT`
Dutch	`nl`	`nl-NL`
Portuguese	`pt`	`pt-PT`
Spanish	`es`	`es-ES`

Calculate Route

Deprecation Notices

Purpose

Run this endpoint

Request data

HTTPS method: GET POST

Generic request format

GET URL example

GET curl command

POST URL example

POST curl command

Types

Request headers

Base path parameters

Request parameters

POST data parameters

Request content example

Response data

Response headers

Response codes

Example of a successful response

Example of an error response

Special behaviour for content type jsonp (JSON with Padding)

Special behavior of certain types of errors (authentication errors, request quota related errors, etc.)

Structure of a successful response

Maneuver codes

Structure of the instruction object

Guidance instruction deprecation policy

Example of a combined message

Tagged messages

Examples of tagged messages

Turn left message

Take exit message

Follow message

Structure of the section object

Structure of an error response

Example of a description string:

Supported languages

HTTPS method: `GET` `POST`

Structure of the `instruction` object

Structure of the `section` object