Calculate Route
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. In addition this endpoint supports guidance functionality that is collectively described in the Guidance Instructions page.
12```shell [type=get] [title=Generic request example]3https://{baseURL}/routing/{versionNumber}/calculateRoute/{routePlanningLocations}/{contentType}?key={Your_API_Key}4&callback={callback}5&maxAlternatives={alternativeRoutes}6&alternativeType={alternativeType}7&minDeviationDistance={integer}8&minDeviationTime={integer}9&supportingPointIndexOfOrigin={integer}10&computeBestOrder={boolean}11&routeRepresentation={routeRepresentation}12&computeTravelTimeFor={trafficTypes}13&vehicleHeading={integer}14§ionType={sectionType}15&report={effectiveSettings}16&departAt={time}17&arriveAt={time}18&routeType={routeType}19&traffic={boolean}20&avoid={avoidType}21&prefer={preferType}22&travelMode={travelMode}23&hilliness={hilliness}24&windingness={windingness}25&vehicleMaxSpeed={vehicleMaxSpeed}26&vehicleWeight={vehicleWeight}27&vehicleAxleWeight={vehicleAxleWeight}28&vehicleLength={vehicleLength}29&vehicleWidth={vehicleWidth}30&vehicleHeight={vehicleHeight}31&vehicleCommercial={boolean}32&vehicleLoadType={vehicleLoadType}33&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}34&vehicleEngineType={vehicleEngineType}35&handsFreeDrivingCapability={handsFreeDrivingCapability}36&constantSpeedConsumptionInLitersPerHundredkm={CombustionConstantSpeedConsumptionPairs}37¤tFuelInLiters={float}38&auxiliaryPowerInLitersPerHour={float}39&fuelEnergyDensityInMJoulesPerLiter={float}40&accelerationEfficiency={float}41&decelerationEfficiency={float}42&uphillEfficiency={float}43&downhillEfficiency={float}44&consumptionInkWhPerkmAltitudeGain={float}45&recuperationInkWhPerkmAltitudeLoss={float}46&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}47¤tChargeInkWh={float}48&maxChargeInkWh={float}49&auxiliaryPowerInkW={float}50&chargeMarginsInkWh={commaSeparatedFloats}51&extendedRouteRepresentation={extendedRouteRepresentation}
GET URL example
Note: Linebreaks are designated by "\".
1https://api.tomtom.com/routing/1/calculateRoute/\252.50931,13.42936:52.50274,13.43872/json?\3&vehicleHeading=90§ionType=traffic\4&report=effectiveSettings&routeType=eco\5&traffic=true&avoid=unpavedRoads\6&travelMode=car&vehicleMaxSpeed=120\7&vehicleCommercial=false&vehicleEngineType=combustion\8&key={Your_API_Key}
GET curl command example
Note: Linebreaks are designated by "\".
1curl -X GET "https://api.tomtom.com/routing/1/calculateRoute/\252.50931,13.42936:52.50274,13.43872/json?\3vehicleHeading=90§ionType=traffic4&report=effectiveSettings\&routeType=eco\5&traffic=true&avoid=unpavedRoads&travelMode=car\6&vehicleMaxSpeed=120&vehicleCommercial=false\7&vehicleEngineType=combustion&key={Your_API_Key}" -H "accept:*/*"
POST 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 example
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.429367 },8 {9 "latitude": 52.50844,10 "longitude": 13.4285911 }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. |
generalizedLocation | A
|
commaSeparatedFloats | Comma-separated list of floats. |
point | To be used in the POST data only. 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 |
---|---|
| The service version number. |
| Locations through which the route is calculated. The following constraints apply:
Values: Colon-delimited |
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 |
---|---|
| Number of desired alternative routes to be calculated. The value provided:
Default value: |
| When
Note: This optional parameter can only be used when reconstructing
a route. |
| All alternative routes returned will follow the reference route (see the
POST data parameters section) from
the origin point of the
0 |
| All alternative routes returned will follow the reference route (see the
POST data parameters section) from
the origin point of the
0 |
| Largest index in the
Minimum value: |
| 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
false |
| Specifies the representation of the set of routes provided as a
response.
Default value:
|
| 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.
Default value: |
| The directional heading of the vehicle, in degrees starting at true North and continuing in a clockwise direction.
Maximum value: |
| Specifies which of the section types is reported in the route response.
Default value:
|
| Specifies a list of margins in kilowatt-hours (kWh) for computing
Minimum value: |
| Specifies the extended representation of the set of routes provided as a
response.
|
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 toeco
, then the Consumption Model will be taken into account for route planning. - When
constantSpeedConsumption*
is specified, the response will include eitherfuelConsumptionInLiters
orbatteryConsumptionInkWh
(forvehicleEngineType
set tocombustion
orelectric
, respectively) as an additional field in eachsummary
element.
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.
- 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. - The alternative routes are calculated between the origin and destination points specified in the
routePlanningLocations
, passing through all intermediate locations specified in thepointWaypoints
field. - If
supportingPointIndexOfOrigin
is not used, and bothminDeviationDistance
andminDeviationTime
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. - 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.
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 thesupportingPoints
.
- The reference route, returned as the first route in the
calculateRoute
response, will start at the origin point specified in thecalculateRoute
request. The initial part of the input reference route up until the origin point will be excluded from the response. - The values of
minDeviationDistance
andminDeviationTime
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 |
pointWaypoints | An array of
|
pointWaypoint | Contains one |
waypointSourceType | Denotes the source of the waypoint. Possible values:
|
supportingPointIndex | An index into the
|
reassessmentParameterSets | An array of
|
Request content example
1{2 "supportingPoints": [3 {"latitude": 52.50930, "longitude": 13.42936},4 {"latitude": 52.50844, "longitude": 13.42859}5 ],6 "pointWaypoints": [7 {8 "waypointSourceType": "USER_DEFINED",9 "supportingPointIndex": 010 }11 ],12 "avoidVignette": [13 "AUS",14 "CHE"15 ],16 "reassessmentParameterSets": [17 {18 "auxiliaryPowerInkW": 0.319 }20 ]21}
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.
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 "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.4291221 },22 "reachableRouteOffsets": [23 {24 "chargeMarginInkWh": 0.0,25 "routeOffsetInMeters": 1147,26 "point": {27 "latitude": 52.51565,28 "longitude": 13.4397929 },30 "pointIndex": 5031 }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.4397944 },45 "pointIndex": 5046 }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.163 },64 "points": [65 {66 "latitude": 52.50931,67 "longitude": 13.4293768 },69 {70 "latitude": 52.50904,71 "longitude": 13.4291272 },73 ...further points...74 ]75 },76 ...further legs...77 ],78 "progress": [79 {80 "pointIndex": 0,81 "travelTimeInSeconds": 0,82 "distanceInMeters": 083 },84 {85 "pointIndex": 5,86 "travelTimeInSeconds": 7,87 "distanceInMeters": 7488 },89 ...further progresses...90 {91 "pointIndex": 87,92 "travelTimeInSeconds": 161,93 "distanceInMeters": 114794 }95 ],96 "sections": [97 {98 "startPointIndex": 0,99 "endPointIndex": 3,100 "sectionType": "TRAVEL_MODE"101 "travelMode": "other"102 },103 {104 "startPointIndex": 3,105 "endPointIndex": 7,106 "sectionType": "TRAVEL_MODE"107 "travelMode": "car"108 },109 {110 "startPointIndex": 2,111 "endPointIndex": 5,112 "sectionType": "TOLL_ROAD"113 },114 {115 "startPointIndex": 3,116 "endPointIndex": 4,117 "sectionType": "TUNNEL"118 },119 {120 "startPointIndex": 0,121 "endPointIndex": 1,122 "sectionType": "PEDESTRIAN"123 },124 {125 "startPointIndex": 3,126 "endPointIndex": 4,127 "sectionType": "TRAFFIC",128 "simpleCategory": "JAM",129 "effectiveSpeedInKmh": 40,130 "delayInSeconds": 158,131 "magnitudeOfDelay": 1,132 "tec": {133 "effectCode": 4,134 "causes": [135 {136 "mainCauseCode": 1137 },138 {139 "mainCauseCode": 26,140 "subCauseCode": 2141 }142 ]143 }144 },145 ...further sections...146 ]147 }148 ...further routes...149 ],150 "optimizedWaypoints": [151 {152 "providedIndex": 0,153 "optimizedIndex": 1154 },155 {156 "providedIndex": 1,157 "optimizedIndex": 0158 }159 ...further optimized waypoints...160 ],161 "report": {162 "effectiveSettings": [163 {164 "key": "avoid",165 "value": "motorways"166 },167 {168 "key": "computeBestOrder",169 "value": "true"170 },171 ...further settings...172 ]173 }174}
Example of an error response
If an error occurs, the response contains the description of the error. The error response would look like this:
1{2 "formatVersion": "0.0.12",3 "detailedError": {4 "code": <error code>,5 "message": "Error message"6 }7}
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.
Special behavior of certain types of errors (authentication errors, request quota related errors, etc.)
- For those errors the HTTP status code is returned as normal (
400
,500
, ...) and the response content type istext/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 |
---|---|
| The format version. |
| The request may return more than one route. |
| The summary of a route, or of a route leg. |
|
|
| A description of a part of a route, comprised of an array of points.
|
| Each object in the array is a location on the surface of the globe
defined by its |
| This array is available inside
|
| Index of the first point (offset |
| Index of the last point (offset |
| A 3-character ISO 3166-1 alpha-3 country code. |
| Type of the incident.
|
| The effective speed of the incident in km/h, averaged over its entire length. |
| The delay in seconds caused by the incident. |
| The magnitude of delay caused by the incident.
These values correspond to the values of the response field
|
| Details of the traffic event. It uses the definitions in the TPEG2-TEC standard. It can contain the |
| The effect on the traffic flow. Contains a value in the
TPEG2-TEC standard. Can be used to color-code traffic events according to severity. |
| Each object in the array describes one cause of the traffic event.
|
| The main cause of the traffic event. Contains a value in the
TPEG2-TEC standard. |
| The subcause of the traffic event. Contains a value in the sub cause
table defined by the TPEG2-TEC standard. |
| The route or leg length in meters. |
| The estimated travel time in seconds. Note that even when
|
| The delay in seconds compared to free-flow conditions according to real-time traffic information. |
| The portion of the route or leg, expressed in meters, that is affected by traffic events which cause the delay. |
| The estimated travel time in seconds calculated as if there are no
delays on the route due to traffic conditions (e.g., congestion).
Included if requested using the |
| The estimated travel time in seconds calculated using time-dependent
historic traffic data. Included if requested using the
|
| The estimated travel time in seconds calculated using real-time speed
data. Included if requested using the |
| The distance (in meters) from the origin point of the
|
| The travel time (in seconds) from the origin point of the
|
| The coordinates of the first point following the origin point of the
|
| The estimated fuel consumption in liters using the Combustion Consumption Model. Included if:
|
| The estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model.
|
| This field is included if
|
| 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:
means that:
Since the index starts by |
| The estimated departure time for the route or leg. Specified as a
|
| The estimated arrival time for the route or leg. Specified as a
|
| Each object in the array represents an effective parameter or a data
used when calling the Calculate Route API. Each object has fields
|
| The original HTTP status code as listed in the response codes (note:
included for content type |
| The reason for a better route proposal. Can currently be:
This field is included in the response only if the route is requested
with |
| This field is included if
A
|
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 | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Contains the response section type.
The
| ||||||||||||||||||||||||||||||
| This field is either set to the value given to the request parameter
|
Structure of an error response
JSON field | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| This object provides a representation of the error message. It contains
a
| ||||||||||||||||||
| The original HTTP status code as listed in response codes (included for
content type |