Calculate Route
Deprecation Notices
Nov 1, 2020
- The
error
response element is deprecated and replaced bydetailedError
- Until its deprecation, both fields are sent in error responses.
- The
message
field indetailedError
contains the same string as thedescription
field inerror
.- 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.
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§ionType={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¤tFuelInLiters={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¤tChargeInkWh={float}45&maxChargeInkWh={float}46&auxiliaryPowerInkW={float}47&chargeMarginsInkWh={commaSeparatedFloats}
GET URL example
Note: Linebreaks are designated by "\".
1https://api.tomtom.com/routing/1/calculateRoute/\252.50931,13.42936:52.50274,13.43872/json?\3instructionsType=text&language=en-US\4&vehicleHeading=90§ionType=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 "\".
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§ionType=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
https://api.tomtom.com/routing/1/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?key={Your_API_Key}
POST 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.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. Example: circle(52.37245,4.89406,10000) |
generalizedLocation | A location or a circle .Examples:
|
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 . |
routePlanningLocations string | Locations through which the route is calculated. The following constraints apply:
generalizedLocation s, 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:
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:
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.
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.
Default value: 0 |
instructionsType string | If specified, guidance instructions will be returned (if available). Possible values are:
|
language string | The language parameter determines the language of the guidance messages.
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:
Default value: false |
routeRepresentation string | Specifies the representation of the set of routes provided as a response. Possible values are:
Default value: polyline Other values:
|
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:
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.
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., ...§ionType=tollRoads§ionType=tollVignettes&... ).Possible values are:
Default value: travelMode Other values:
|
chargeMarginsInkWh commaSeparatedFloats | Specifies a list of margins in kilowatt-hours (kWh) for computing reachableRouteOffsets .
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 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 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
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. - Intermediate locations (
waypoints
) are not supported when usingsupportingPoints
. - 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 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 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
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.313 }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.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 "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": 1119 },120 {121 "mainCauseCode": 26,122 "subCauseCode": 2123 }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.42937137 },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": 1166 },167 {168 "providedIndex": 1,169 "optimizedIndex": 0170 }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:
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.
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 |
---|---|
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 |
|
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 insideroute objects.
|
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.
|
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:
ty of the Online Traffic Incident Details. |
tec object | Details of the traffic event.
|
effectCode number | The effect on the traffic flow.
|
causes array of objects | Each object in the array describes one cause of the traffic event.
|
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.
|
deviationTime number | The travel time (in seconds) from the origin point of thecalculateRoute request to the first point where this route forks off from the reference route.
|
deviationPoint object | The coordinates of the first point following the origin point of thecalculateRoute request where this route forks off from the reference route.
|
fuelConsumptionInLiters number | The estimated fuel consumption in liters using the Combustion Consumption Model. Included if:
|
batteryConsumptionInkWh number | The estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model.
|
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.
|
optimizedWaypoints array of objects | A description of an optimized sequence of waypoints.
|
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.
|
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:
alternativeType=betterRoute .This field is not present in the leg summary 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
|
pointIndex number | The index of the point in the array of polyline points.Equivalent to startPointIndex and endPointIndex in sections:
|
instructionType string | The type of instruction, e.g., a turn or a change of road form. Possible values:
|
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
|
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:
|
turnAngleInDecimalDegrees number | Indicates the direction of an instruction. If junctionType indicates a turn instruction:
junctionType indicates a bifurcation instruction:
|
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:
|
drivingSide string | Indicates left-hand vs. right-hand side driving at the point of the maneuver. Possible values:
|
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:
10. Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam11. 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:
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.
The A A
| ||||||||||||||||||||||||||
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.
| ||||||||||||||||
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 |