Guidance Instructions

Service version: 1

Last edit: 2024.01.16

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 following direction (`follow`) where possible, 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]`.

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 following direction (follow) where possible, 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	Example of supported regions	Unsupported regions
Arabic	Algeria, Egypt, Morocco, Saudi Arabia, Tunisia	Jordan, Lebanon, North Africa
Basque	Spain, France
Bulgarian	Bulgaria
Bulgarian	Latin
Catalan	Spain
Chinese	Taiwan Mandarin (traditional)	China Simplified, Hong Kong Cantonese
Croatian	Croatie
Czech	Czech Republic
Danish	Denmark
Dutch	Belgium, Netherlands, Southern Africa
English	Canada, UK, India, Singapore, USA, South Africa	Australia, New Zealand
Finnish	Finland
French	Belgium, Canada, France, Morocco, Tunisia
Galician	Spain
German	Austria, Belgium, Germany, Namibia	Switzerland, Luxemburg
Greek	Greece
Hungarian	Hungary
Icelandic	Iceland
Indonesian	Indonesian, Indonesia
Italian	Italy
Malay	Malaysia
Polish	Poland
Portuguese	Brazil, Portugal
Romanian	Romania
Russian	Latin
Russian	Russian Federation
Slovak	Slovakia
Slovenian	Slovenia
Spanish	Argentina, Central America, Chile, Colombia, Spain, Mexico, Peru, Uruguay, USA	Venezuela
Swedish	Finland, Sweden

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{
"formatVersion": "0.0.12",
"roadShieldAtlasReference": "https://api.tomtom.com/map/1/roadshield/1.0.0/",
"routes": [
  {
    "summary": [...]
    "legs": [...]
    "sections": [
      {
        "lanes": [
          {
            "directions": ["STRAIGHT"]
          },
          {
            "directions": ["SLIGHT_RIGHT"],
            "follow": "SLIGHT_RIGHT"
          }
        ],
        "laneSeparators": ["SINGLE_SOLID", "DOUBLE_SOLID", "SINGLE_SOLID"],
        "startPointIndex": 48,
        "endPointIndex": 49,
        "sectionType": "LANES"
      },
      {
        "lanes": [
          {
            "directions": ["STRAIGHT"],
            "follow": "STRAIGHT"
          },
          {
            "directions": ["STRAIGHT"],
            "follow": "STRAIGHT"
          },
          {
            "directions": ["RIGHT"]
          }
        ],
        "laneSeparators": ["SINGLE_SOLID", "SINGLE_SOLID", "SHORT_DASHED", "SINGLE_SOLID"],
        "startPointIndex": 52,
        "endPointIndex": 53,
        "sectionType": "LANES"
      },
      {
        "maxSpeedLimitInKmh": 120,
        "startPointIndex": 53,
        "endPointIndex": 54,
        "sectionType": "SPEED_LIMIT"
      },
      {
        "maxSpeedLimitInKmh": 50,
        "startPointIndex": 60,
        "endPointIndex": 64,
        "sectionType": "SPEED_LIMIT"
      },
      {
        "roadShieldReferences": [
          {
            "reference": "nld-highway",
            "shieldContent": "2"
          },
          {
            "reference": "european-road",
            "shieldContent": "E1",
            "affixes": [
                "N"
              ]
          },
...further road shield references...
        ],
        "startPointIndex": 42,
        "endPointIndex": 68,
        "sectionType": "ROAD_SHIELDS"
      }
...further sections...
    ]
    "guidance": {
      "instructions": [
...prior instructions...
          {
          "routeOffsetInMeters" : 1141,
          "travelTimeInSeconds" : 236,
          "point" : {
              "latitude" : 52.37236,
              "longitude" : 4.90861
            },
          "pointIndex" : 64,
          "instructionType" : "TURN",
          "roadNumbers" : ["s116"],
          "phoneticRoadNumbers" : ["'2Es.hOn.d$rt.sEs.'tin"],
          "phoneticRoadNumberLanguageCodes" : ["DUN"],
          "street" : "Prins Hendrikkade",
          "phoneticStreet" : "'prIns_'hEn.drIk.'2ka.d$",
          "phoneticStreetLanguageCode" : "DUN",
          "countryCode" : "NLD",
          "signpostText" : "Scheepvaartmuseum",
          "phoneticSignPostText" : "'sxep.fart.my.'2ze.^m",
          "phoneticSignPostTextLanguageCode" : "DUN",
          "junctionType" : "BIFURCATION",
          "turnAngleInDecimalDegrees" : 45,
          "possibleCombineWithNext" : true,
          "drivingSide" : "RIGHT",
          "maneuver" : "KEEP_RIGHT",
          "message" : "Keep right at Prins Hendrikkade toward Scheepvaartmuseum",
          "combinedMessage" : "Keep right at Prins Hendrikkade toward Scheepvaartmuseum then keep left at Prins Hendrikkade/s116",
          "roadShieldReferences": [
            {
              "reference": "european-road",
              "shieldContent": "E1",
              "affixes": [
                "E"
              ]
            }
          ],
          "signpostRoadShieldReferences": [
            {
              "reference": "nld-connector",
              "shieldContent": "s100"
            }
          ],
          "earlyWarningAnnouncement" : {
            "point" : {
              "latitude" : 52.3747,
              "longitude" : 4.90426
            },
            "pointIndex" : 43,
            "maneuver" : "AHEAD_KEEP_RIGHT",
            "distanceInMeters" : 400
          },
          "mainAnnouncement" : {
            "point" : {
              "latitude" : 52.37353,
              "longitude" : 4.90645
            },
            "pointIndex" : 50,
            "maneuver" : "KEEP_RIGHT",
            "distanceInMeters" : 200
          },
          "confirmationAnnouncement" : {
            "point" : {
              "latitude" : 52.37263,
              "longitude" : 4.90785
            },
            "pointIndex" : 58,
            "maneuver" : "KEEP_RIGHT",
            "distanceInMeters" : 60
          }
        },
  ...further instructions...
      ],
      "instructionGroups": [
        {
          "firstInstructionIndex": 0,
          "lastInstructionIndex": 5,
          "groupLengthInMeters": 4567,
          "groupMessage": "Leave from An der Schillingbrücke and continue to A1/E35"
        },
...further instruction groups...
      ]
    }
  }
...further routes...
]
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
`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` 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 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`
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`

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
`UNKNOWN`	No information.
`NO_MARKING`	No marking.
`LONG_DASHED`	Long dashed line.
`DOUBLE_SOLID`	Double solid line.
`SINGLE_SOLID`	Single 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_DASHED`	Short dashed line.
`SHADED_AREA_MARKING`	Shaded area marking.
`DASHED_BLOCKS`	Dashed blocks.
`DOUBLE_DASHED`	Double dashed line.
`CROSSING_ALERT`	Marking for crossing which looks like a zigzag line.
`PHYSICAL_DIVIDER`	Physical 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_RIGHT`	Ahead, keep right.
`AHEAD_RIGHT_TURN`	Right-turn ahead.
`AHEAD_KEEP_LEFT`	Ahead, keep left.
`AHEAD_LEFT_TURN`	Left-turn ahead.
`AHEAD_UTURN`	U-turn ahead.
`AHEAD_EXIT`	Exit ahead.
`AHEAD_EXIT_RIGHT`	Exit right ahead.
`AHEAD_EXIT_LEFT`	Exit left ahead.
`AHEAD_TAKE_FERRY`	Ahead, take the ferry.
`WAYPOINT_APPROACH`	Approaching waypoint.

Guidance Instructions

Purpose

Types

Request data

HTTPS method: GET POST

Generic request format

GET URL example

GET curl command example

Extensions of existing features

sectionType parameter

Request parameters

Response data

Example of a successful response

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

Supported languages

Lane section information

Extra maneuver codes for instruction announcement points

HTTPS method: `GET` `POST`

Structure of the `instruction` object