Guidance Instructions

Service version: 1
Last edit: 2024.01.16
TomTom Maps

Purpose

This document describes route planning parameters that are related to the guidance. They can be used, among others, in the Calculate Route service.

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

Types

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
Generic request example
1https://{baseURL}/routing/{versionNumber}/calculateRoute/{routePlanningLocations}/{contentType}?key={Your_API_Key}
2&instructionsType={instructionsType}
3&language={language}
4&sectionType={sectionType}
5&instructionAnnouncementPoints={string}
6&instructionPhonetics={string}
7&instructionRoadShieldReferences={string}

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?\
3&instructionsType=text&language=en-GB\
4&sectionType=lanes&instructionAnnouncementPoints=all\
5&instructionPhonetics=LHP&instructionRoadShieldReferences=all\
6&key={Your_API_Key}

GET curl command example

Note: Linebreaks are designated by "\".

get
Request curl command example
1curl -X GET "https://api.tomtom.com/routing/1/calculateRoute/\
252.50931,13.42936:52.50274,13.43872/json?\
3&instructionsType=text&language=en-GB\
4&sectionType=lanes&instructionAnnouncementPoints=all\
5&instructionPhonetics=LHP&instructionRoadShieldReferences=all\
6&key={Your_API_Key}" -H "accept:*/*"

Extensions of existing features

sectionType parameter

Parameter

Description

sectionType
string

The following section types can additionally be requested:

  • lanes: Sections with lane information. This is a combination of lane directions (directions), including the follow direction (follow) where recommended, and lane markings on the road (laneSeparators).

    • Lanes are given left-to-right with the direction of travel.

    • Separators are also given left-to-right, starting with the marking to left of the left-most lane and ending with the marking to the right of the right-most lane, such that laneSeparator[x] is to the left of lane[x] .

Request parameters

Optional parameters

Description

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 returned names and 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

instructionAnnouncementPoints
string

Specifies whether to include announcement points in instructions. If specified, the instruction will include up to three additional fine-grained announcement points, each with their own location, maneuver type, and distance to the instruction point.

Possible values are:

  • none: Do not include instruction announcement points in instructions.

  • all: Include instruction announcement points in instructions, exposing the following instruction fields, where applicable:

    • earlyWarningAnnouncement
    • mainAnnouncement
    • confirmationAnnouncement

    Each of these announcements has the following fields:

    • point: Location of the announcement. It is a point object (see Types).

    • pointIndex: Largest index in the polyline of the route for which points[pointIndex] lies on or before point .

    • maneuver: Maneuver code. Possible values include all possible values of the maneuver instruction field as well as all extra maneuver codes for instruction announcement points.

    • distanceInMeters: Distance in meters from point to the point in instruction.

    The semantics of point, pointIndex, and maneuver are equivalent to their counterparts of the same name in instruction.

Default value: none.

instructionPhonetics
string

Specifies whether to include the phonetic transcription of street names, signpost text, and road numbers in the instructions of the response.

Possible values are:

  • none: Do not include phonetic transcriptions in the response.

  • LHP: Return phonetic transcriptions in the L&H+ format from Cerence Inc.

  • IPA: Return phonetic transcriptions in the IPA (International Phonetic Alphabet) format.

Default value: none.

When using any value other than none, phonetic information will be returned in the response as follows:

  • Instructions containing a street field are extended with:

    • phoneticStreet: a phonetic string in the requested phonetic format.

    • phoneticStreetLanguageCode: language code in which the phonetic string is encoded.

  • Instructions containing a signpostText field are extended with:

    • phoneticSignpostText: a phonetic string in the requested phonetic format.

    • phoneticSignpostTextLanguageCode: language code in which the phonetic string is encoded.

  • Instructions containing a roadNumbers array are extended with:

    • phoneticRoadNumbers: array of phonetic strings in the requested phonetic format corresponding to the respective elements of the roadNumbers array.

    • phoneticRoadNumberLanguageCodes: array of language codes in which the respective phonetic strings are encoded.

Note: In areas where phonetic information is not available, these fields will not be returned in the Response. The LanguageCode encodes the language in the Nuance encoding for the L&H+ phonetic format and uses IETF language tags for the rest, e.g., en-GB, en-US. L&H+ has, on top of availability, limited support to the following languages:

Language
Afrikaans
Albanian
Arabic
Bahasa Indonesian
Basque
Bosnian
Breton
Bulgarian
Catalan
Chinese Mandarin
Corsican
Czech
Danish
Dutch
English
Finnish
French
Frisian
Galician
German
Greek
Hungarian
Icelandic
Irish
Italian
Malay
Norwegian Bokmål
Occitan
Polish
Portuguese
Romanian
Russian
Scottish Gaelic
Serbian
Serbo-Croat
Slovak
Slovenian
Spanish
Swedish
Valencian
Welsh

instructionRoadShieldReferences
string

Specifies whether to include road shield references into the external road shields atlas.
If this parameter is set to all, then:

  • Instructions contain a roadShieldReferences and a signpostRoadShieldReferences element where such data is available.

    • roadShieldReferences refers to the road shields of the next significant road segment after the maneuver.

    • signpostRoadShieldReferences refers to the road shields on the signpost which is most relevant to the maneuver.

  • calculateRouteResponse contains an additional field roadShieldAtlasReference. Please refer to the notes about the road shield atlas for further information.

Possible values are:

  • none: Do not include road shield references in the Response.

  • all: Include road shield references in the response.

Default value: none.


The road shields are available in these supported countries.

Response data

Example of a successful response

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

Response body - JSON
1{
2 "formatVersion": "0.0.12",
3 "roadShieldAtlasReference": "https://api.tomtom.com/map/1/roadshield/1.0.0/",
4 "routes": [
5 {
6 "summary": [...]
7 "legs": [...]
8 "sections": [
9 {
10 "lanes": [
11 {
12 "directions": ["STRAIGHT"]
13 },
14 {
15 "directions": ["SLIGHT_RIGHT"],
16 "follow": "SLIGHT_RIGHT"
17 }
18 ],
19 "laneSeparators": ["SINGLE_SOLID", "DOUBLE_SOLID", "SINGLE_SOLID"],
20 "startPointIndex": 48,
21 "endPointIndex": 49,
22 "sectionType": "LANES"
23 },
24 {
25 "lanes": [
26 {
27 "directions": ["STRAIGHT"],
28 "follow": "STRAIGHT"
29 },
30 {
31 "directions": ["STRAIGHT"],
32 "follow": "STRAIGHT"
33 },
34 {
35 "directions": ["RIGHT"]
36 }
37 ],
38 "laneSeparators": ["SINGLE_SOLID", "SINGLE_SOLID", "SHORT_DASHED", "SINGLE_SOLID"],
39 "startPointIndex": 52,
40 "endPointIndex": 53,
41 "sectionType": "LANES"
42 },
43 {
44 "maxSpeedLimitInKmh": 120,
45 "startPointIndex": 53,
46 "endPointIndex": 54,
47 "sectionType": "SPEED_LIMIT"
48 },
49 {
50 "maxSpeedLimitInKmh": 50,
51 "startPointIndex": 60,
52 "endPointIndex": 64,
53 "sectionType": "SPEED_LIMIT"
54 },
55 {
56 "roadShieldReferences": [
57 {
58 "reference": "nld-highway",
59 "shieldContent": "2"
60 },
61 {
62 "reference": "european-road",
63 "shieldContent": "E1",
64 "affixes": [
65 "N"
66 ]
67 },
68 ...further road shield references...
69 ],
70 "startPointIndex": 42,
71 "endPointIndex": 68,
72 "sectionType": "ROAD_SHIELDS"
73 }
74 ...further sections...
75 ]
76 "guidance": {
77 "instructions": [
78 ...prior instructions...
79 {
80 "routeOffsetInMeters" : 1141,
81 "travelTimeInSeconds" : 236,
82 "point" : {
83 "latitude" : 52.37236,
84 "longitude" : 4.90861
85 },
86 "pointIndex" : 64,
87 "instructionType" : "TURN",
88 "roadNumbers" : ["s116"],
89 "phoneticRoadNumbers" : ["'2Es.hOn.d$rt.sEs.'tin"],
90 "phoneticRoadNumberLanguageCodes" : ["DUN"],
91 "street" : "Prins Hendrikkade",
92 "phoneticStreet" : "'prIns_'hEn.drIk.'2ka.d$",
93 "phoneticStreetLanguageCode" : "DUN",
94 "countryCode" : "NLD",
95 "signpostText" : "Scheepvaartmuseum",
96 "phoneticSignPostText" : "'sxep.fart.my.'2ze.^m",
97 "phoneticSignPostTextLanguageCode" : "DUN",
98 "junctionType" : "BIFURCATION",
99 "turnAngleInDecimalDegrees" : 45,
100 "possibleCombineWithNext" : true,
101 "drivingSide" : "RIGHT",
102 "maneuver" : "KEEP_RIGHT",
103 "message" : "Keep right at Prins Hendrikkade toward Scheepvaartmuseum",
104 "combinedMessage" : "Keep right at Prins Hendrikkade toward Scheepvaartmuseum then keep left at Prins Hendrikkade/s116",
105 "roadShieldReferences": [
106 {
107 "reference": "european-road",
108 "shieldContent": "E1",
109 "affixes": [
110 "E"
111 ]
112 }
113 ],
114 "signpostRoadShieldReferences": [
115 {
116 "reference": "nld-connector",
117 "shieldContent": "s100"
118 }
119 ],
120 "earlyWarningAnnouncement" : {
121 "point" : {
122 "latitude" : 52.3747,
123 "longitude" : 4.90426
124 },
125 "pointIndex" : 43,
126 "maneuver" : "AHEAD_KEEP_RIGHT",
127 "distanceInMeters" : 400
128 },
129 "mainAnnouncement" : {
130 "point" : {
131 "latitude" : 52.37353,
132 "longitude" : 4.90645
133 },
134 "pointIndex" : 50,
135 "maneuver" : "KEEP_RIGHT",
136 "distanceInMeters" : 200
137 },
138 "confirmationAnnouncement" : {
139 "point" : {
140 "latitude" : 52.37263,
141 "longitude" : 4.90785
142 },
143 "pointIndex" : 58,
144 "maneuver" : "KEEP_RIGHT",
145 "distanceInMeters" : 60
146 }
147 },
148 ...further instructions...
149 ],
150 "instructionGroups": [
151 {
152 "firstInstructionIndex": 0,
153 "lastInstructionIndex": 5,
154 "groupLengthInMeters": 4567,
155 "groupMessage": "Leave from An der Schillingbrücke and continue to A1/E35"
156 },
157 ...further instruction groups...
158 ]
159 }
160 }
161 ...further routes...
162 ]
163}

Structure of a successful response

JSON field

Description

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.

roadShieldReferences
signpostRoadShieldReferences
arrays of roadShieldReference objects

A roadShieldReference object describes a single road shield reference. Please refer to the structure of a road shield reference object for further information.

Maneuver codes

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

Maneuver value

Example translation

ARRIVEYou have arrived.
ARRIVE_LEFTYou have arrived. Your destination is on the left.
ARRIVE_RIGHTYou have arrived. Your destination is on the right.
DEPARTLeave.
STRAIGHTKeep straight on.
KEEP_RIGHTKeep right.
BEAR_RIGHTBear right.
TURN_RIGHTTurn right.
SHARP_RIGHTTurn sharp right.
KEEP_LEFTKeep left.
BEAR_LEFTBear left.
TURN_LEFTTurn left.
SHARP_LEFTTurn sharp left.
MAKE_UTURNMake a U-turn.
ENTER_MOTORWAYTake the motorway.
ENTER_FREEWAYTake the freeway.
ENTER_HIGHWAYTake the highway.
TAKE_EXITTake the exit.
MOTORWAY_EXIT_LEFTTake the left exit.
MOTORWAY_EXIT_RIGHTTake the right exit.
TAKE_FERRYTake the ferry.
ROUNDABOUT_CROSSCross the roundabout.
ROUNDABOUT_RIGHTAt the roundabout take the exit on the right.
ROUNDABOUT_LEFTAt the roundabout take the exit on the left.
ROUNDABOUT_BACKGo around the roundabout.
TRY_MAKE_UTURNTry to make a U-turn.
FOLLOWFollow.
SWITCH_PARALLEL_ROADSwitch to the parallel road.
SWITCH_MAIN_ROADSwitch to the main road.
ENTRANCE_RAMPTake the ramp.
WAYPOINT_LEFTYou have reached the waypoint. It is on the left.
WAYPOINT_RIGHTYou have reached the waypoint. It is on the right.
WAYPOINT_REACHEDYou 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
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 namestreet
Road numberroadNumber
Signpost textsignpostText
Exit number - motorwayexitNumber
Exit number - roundaboutroundaboutExitNumber

Examples of tagged messages

Turn left message

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

Take exit message

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

Follow message

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

Supported languages

Language name

Language tag

Afrikaans (South Africa)af-ZA
Arabicar
Bulgarianbg-BG
Chinese (Taiwan)zh-TW
Czechcs-CZ
Danishda-DK
Dutchnl-NL
English (Great Britain)en-GB
English (USA)en-US
Finnishfi-FI
Frenchfr-FR
Germande-DE
Greekel-GR
Hungarianhu-HU
Indonesianid-ID
Italianit-IT
Koreanko-KR
Lithuanianlt-LT
Malayms-MY
Norwegiannb-NO
Polishpl-PL
Portuguese (Brazil)pt-BR
Portuguese (Portugal)pt-PT
Russianru-RU
Slovaksk-SK
Sloveniansl-SI
Spanish (Castilian)es-ES
Spanish (Mexico)es-MX
Swedishsv-SE
Thaith-TH
Turkishtr-TR

The following language code abbreviations are also supported:

Language name

Language tag

Inferred language tag

Englishenen-GB
Frenchfrfr-FR
Germandede-DE
Italianitit-IT
Dutchnlnl-NL
Portugueseptpt-PT
Spanisheses-ES

Lane section information

The following table describes the possible values of the directions and follow fields in the lanes section.

Directions value

STRAIGHT
SLIGHT_RIGHT
RIGHT
SHARP_RIGHT
RIGHT_U_TURN
SLIGHT_LEFT
LEFT
SHARP_LEFT
LEFT_U_TURN

The following table describes the possible values of the laneSeparators field in the lanes section.

Lane separators value

Description

UNKNOWNNo information.
NO_MARKINGNo marking.
LONG_DASHEDLong dashed line.
DOUBLE_SOLIDDouble solid line.
SINGLE_SOLIDSingle solid line.
SOLID_DASHED

Solid line and dashed line in parallel as seen from left to right.

DASHED_SOLID

Dashed line and solid line in parallel as seen from left to right.

SHORT_DASHEDShort dashed line.
SHADED_AREA_MARKINGShaded area marking.
DASHED_BLOCKSDashed blocks.
DOUBLE_DASHEDDouble dashed line.
CROSSING_ALERTMarking for crossing which looks like a zigzag line.
PHYSICAL_DIVIDERPhysical divider.

Extra maneuver codes for instruction announcement points

The following table describes the additional possible values of the maneuver instruction announcement point field. Please note that the Guidance instruction deprecation policy still applies.

Maneuver value

Example translation

AHEAD_KEEP_RIGHTAhead, keep right.
AHEAD_RIGHT_TURNRight-turn ahead.
AHEAD_KEEP_LEFTAhead, keep left.
AHEAD_LEFT_TURNLeft-turn ahead.
AHEAD_UTURNU-turn ahead.
AHEAD_EXITExit ahead.
AHEAD_EXIT_RIGHTExit right ahead.
AHEAD_EXIT_LEFTExit left ahead.
AHEAD_TAKE_FERRYAhead, take the ferry.
WAYPOINT_APPROACHApproaching waypoint.