Guidance Instructions
Purpose
This document describes route planning parameters that are related to guidance instructions. They can be used 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.
Request data
HTTPS methods: POST
The functionality described here extends the functionality of the endpoint described in Calculate Route .
Note: Only additional parameters and behaviours over the ones in Calculate Route are explicitly listed.
curl -X POST "https://api.tomtom.com/maps/orbis/routing/routes/calculate" -H "Content-type:application/json" -H "TomTom-Api-Version:3" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:routes" -d \'{ "routePlanningLocations": { "origin": { "type": "Point", "coordinates": [13.42936, 52.50931] }, "destination": { "type": "Point", "coordinates": [13.43872, 52.50274] } }, "guidance": "instructions", "instructionPhonetics": "ipa"}'POST data parameters
The guidance parameter controls whether guidance instructions are going to be included in the response. In case
guidance instructions are requested, instructionPhonetics control the type of the phonetic translations of the name
fields returned in the response.
To enable Guidance Instructions, set the guidance parameter to instructions. Omitting the parameter (or setting its
value to none) will disable Guidance Instructions.
Parameter | Description |
|---|---|
| Possible values are |
| Possible values are Setting it to This parameter is mandatory if |
The Accept-Language header
In scope of guidance instruction API this header controls:
The language in which proper names (e.g. street names) are returned in the coded instruction fields, along with their phonetic transcriptions. If the names are not available in the requested language, the engine will return them in the closest available language.
The language in which the human readable instruction text is generated. If the language is not available for instruction text generation and the human readable messages were requested, this will result in a user error.
See Calculate Route for the general description.
Response data
Example of a successful response
Note: The example below intentionally includes all fields defined in this specification. In actual responses, certain fields are mutually exclusive and the set of returned fields varies based on the maneuver type associated with each instruction.
Successful response body
{ [...] "routes": [ { "summary": [...] "legs": [...], "instructions": [ ...prior instructions... { "routeOffsetInMeters": 1141, "maneuverPoint": { "latitude": 52.37236, "longitude": 4.90861 }, "routePath": [ { "point" : { "latitude": 52.37236, "longitude": 4.90861 }, "distanceFromRouteStartInMeters" : 1150, "travelTimeFromRouteStartInSeconds" : 45 }, { "point" : { "latitude": 52.37245, "longitude": 4.90831 }, "distanceFromRouteStartInMeters" : 1160, "travelTimeFromRouteStartInSeconds" : 46 }, { "point" : { "latitude": 52.37255, "longitude": 4.90805 }, "distanceFromRouteStartInMeters" : 1170, "travelTimeFromRouteStartInSeconds" : 47 } ], "maneuver": "turnRight", "maneuverView": { "onRouteAngle": "right", "offRouteAngles": ["straight", "left"] }, "previousRoadInformation": { "properties": ["motorway"], "streetName": { "text": "Max-Brauer-Allee", "phonetic": "maks \"braU|6 ?a|\"le:", "phoneticLanguageCode": "de-DE" }, "roadShields": [ { "roadNumber": { "text": "b208", "phonetic": "be: %tsvaI|hUn|d6t|\"?axt", "phoneticLanguageCode": "de-DE", }, "countryCodeIso2": "NL" }, ...further road shields... ], }, "nextRoadInformation": { "properties": ["motorway", "urban"], "streetName": { "text": "Schnellstraße", "phonetic": "SnEl|%Stra:|s@", "phoneticLanguageCode": "de-DE" }, "roadShields": [ { "roadNumber": { "text": "a2", "phonetic": "?a: \"tsvaI", "phoneticLanguageCode": "de-DE", }, "countryCodeIso2": "NL" }, { "roadNumber": { "text": "a12", "phonetic": "?a: \"tsv9lf", "phoneticLanguageCode": "de-DE", }, "countryCodeIso2": "NL" }, ...further road shields... ] }, "signpost": { "exitName": { "text": "Grünewald", "phonetic": "gru:|n@|%valt", "phoneticLanguageCode": "de-DE" }, "exitNumber": { "text": "3", "phonetic": "dRaI", "phoneticLanguageCode": "de-DE" }, "towardName": { "text": "Potsdam", "phonetic": "pOts|dam", "phoneticLanguageCode": "de-DE" }, }, "intersectionName": { "text": "Oranienenburger Tor", "phonetic": "?o:|\"ra:|nj@n|%bUr|g6 \"to:6^", "phoneticLanguageCode": "de-DE" }, "isManeuverObligatory": false, "changeOfAngleInDegrees": 45, "roundaboutExitNumber": 2, "roundaboutType": "regular", "tollgateName": { "text": "Koblenz", "phonetic": "ko:|blEnts", "phoneticLanguageCode": "de-DE" }, "tollPaymentTypes": [ "creditCard", "debitCard", "etc", "etcTransponder", "etcVideoCamera", "subscription" ], "countryCrossingFromName": { "text": "Frankreich", "phonetic": "fraNk|raIC", "phoneticLanguageCode": "de-DE" }, "countryCrossingFromCodeIso2": "FR", "countryCrossingToName": { "text": "Deutschland", "phonetic": "dOYtS|lant", "phoneticLanguageCode": "de-DE" }, "countryCrossingToCodeIso2": "DE", "drivingSide": "right", "landmark": "atTrafficLight", "distanceToPreviousTrafficLightInMeters": 18, "ambiguousExitOffsetFromManeuverInMeters": 27, "instructionMessage" : "Turn right onto Schnellstraße.", "sideRoads": [ { "side": "left", "offsetFromManeuverInMeters": 66, "isDrivable": true }, { "side": "right", "offsetFromManeuverInMeters": 42, "isDrivable": false }, ...further side roads... ] }, ...further instructions... ], } ...further routes... ], ...} Structure of the Instruction object
Common fields for all maneuvers
JSON field | Description |
|---|---|
| A code identifying the maneuver. Possible values:
|
| A representative point of the maneuver. Note: Can be used to depict a maneuver as a single point on the map, but no further assumptions how it relates to other attributes must be made. |
| The distance on route from the start of the route to the |
| A maneuver’s geometry is defined as a polyline, which may consist of multiple coordinate points. For such
maneuvers, this field returns the ordered list of points that constitute the maneuver’s geometry. For maneuvers
that only occupy a single point, this field will contain a single array item, with a |
| Provides information about the road in the link before the maneuver. |
| Provides information about the road that the route continues onto immediately after the maneuver. If a signpost related to the maneuver is available this information is taken from it. Otherwise it is obtained from the road segment beyond the maneuver. |
| Present only when a signpost associated with this maneuver is available. Provides the signpost information that corresponds to the maneuver and indicates the subsequent direction along the route. |
| Name of the intersection at which the maneuver must be performed. Included if intersection name is available for this maneuver. |
| Indicates whether driving at the maneuver location follows left‑hand or right‑hand traffic rules. Possible values:
|
| A notable feature near the maneuver that can help orient the driver. Included if a landmark is available for this maneuver. Possible values:
|
| List of roads that connect to the route immediately before the maneuver but are not part of the route itself. These are roads that a driver could mistakenly take, because they may appear drivable based on the instruction alone, even though they are excluded from the route due to dynamic restrictions such as time-dependent or vehicle-profile-dependent rules. Dual-carriageway roads may be represented as a single side road or as several, depending on how the driver would perceive them. The list is empty if no roads connect to the route before the maneuver. It is ordered by ascending offset along the route. This information can be used for a richer graphical representation of the maneuver, visualizing connected roads in proximity before it. Included if there are side roads within a reasonable distance before the maneuver. |
| Schematic representation of the intersection for the maneuver. Intersection is considered as a point with connected roads. Included if the maneuver is bound to an intersection. |
| A human‑readable instruction message intended for display or text‑to‑speech output. The message is generated based on the maneuver and its attributes, and is localized to the language specified in the request. |
Additional fields for turn maneuvers
| Marks this maneuver as obligatory. For example, when a driver reaches a T-junction, where one option is
drivable, while the other is not. Included if the maneuver is a turn maneuver, i.e.,
Note that the |
|---|
Additional fields for turn and roundabout maneuvers
| Represents the total change of angle (in degrees) from the entry until the exit of the maneuver, within the
range
|
|---|
Additional fields for switch motorway maneuvers
| The route offset (in meters) indicating where the route merges onto the new motorway. Applicable for maneuvers
where
|
|---|
Additional fields for exit motorway, switch motorway, and exit roundabout maneuvers
| Included if current maneuver is an exit, and there is another exit before the current maneuver within reasonable
distance, which may cause ambiguity. In such case there might be a need to resolve the ambiguity on client
side, and compose an instruction like “Take the 2nd exit”. Represents the offset (on route) of the ambiguous
exit from the maneuver point (represented by
|
|---|
Additional fields for roundabout maneuvers
| The ordinal number of the exit to take at a roundabout, e.g., “take the first/second exit”. Included if the
maneuver is a roundabout maneuver, i.e.
|
|---|---|
| Indicates the roundabout type. Possible values:
Included if the maneuver is a roundabout maneuver, i.e.
|
Additional fields for tollgate maneuvers
| The name of the tollgate, if available. Included if the maneuver is a tollgate maneuver, i.e., |
|---|---|
| Array containing one or more available toll payment options for this tollgate. Possible values are:
|
Additional fields for maneuvers leading to a border crossing
| The name of the country the border crossing occurs from. Included if the maneuver is a border crossing maneuver,
or leads to a border crossing, i.e.
|
|---|---|
| Country code (ISO 3166-1 alpha-2) of the country the border crossing occurs from. Included if the
|
| The name of the country the border crossing occurs to. Included if the maneuver is a border crossing maneuver,
i.e.
|
| Country code (ISO 3166-1 alpha-2) of the country the border crossing occurs to. Included if the
|
Structure of the RoutePathPoint object
JSON field | Description |
|---|---|
| The latitude and longitude of the point on the map. See Calculate Route . |
| Distance (in meters) from the start of the route to this point. |
| Travel duration (in seconds) from the start of the route to this point. |
Structure of the RoadInformation object
JSON field | Description |
|---|---|
| The properties of road, as a possible combination of several values. Possible values:
|
| Lists the road shields for this road. The list can be empty if no road shields are available. |
| Lists the road numbers with phonetic information, road attribute, and source. |
| Lists the road names with phonetic information and source. |
| Country code (ISO 3166-1 alpha-2) of the country. |
Structure of the Signpost object
JSON field | Description |
|---|---|
| Exit name of the controlled access road. Included if an exit name is available for this signpost. |
| Exit number of the controlled access road. Included if an exit number is available for this signpost. If the exit number is not available, the field will be absent. |
| The toward name from the signpost. |
Structure of the TextWithPhonetics object
JSON field | Description |
|---|---|
| The name as a text string. |
| The phonetic transcription of the name. Included if phonetic transcription is available for the specific name,
and phonetic transcriptions have been requested by the client.
Note: The phonetic transcription can contain double quote characters ( |
| BCP47 language code indicating the language of the phonetic transcription. For example, “en-GB” for English as used in the United Kingdom, “de-DE” for German as used in Germany, etc. Included if phonetic transcription is available for the specific name, and phonetic transcriptions have been requested by the client. |
Structure of the SideRoad object
JSON field | Description |
|---|---|
| Side from where the road connects to the route. Possible values:
|
| Offset (on route) of the side road from the maneuver point (represented by |
| Whether the side road is drivable or not. |
Structure of the ManeuverView object
JSON field | Description |
|---|---|
| The quantized angle of the on-route outgoing road relative to the driving direction. Possible values:
|
| The quantized angles of the off-route outgoing roads relative to the driving direction. Possible values:
|
Structure of the RoadShield object
JSON field | Description |
|---|---|
| The road number. Most road numbers have a ‘letter’ prefix, which is also returned. For example, a call for the German motorway returns “A40” rather than “40”. |
| The state code of the state the shield is in, as an ISO 3166-2 identifier. Included if sub-country codes are available for the country the road shield is located in. |
| Country code (ISO 3166-1 alpha-2) of the country the shield is in. |
Structure of the RoadIdentifier object
JSON field | Description |
|---|---|
| Text and phonetic transcription of the road number or name. |
| Indicates the origin of the road identifier data. Possible values:
|
| Special road attribute of the road identifier. Note that these are currently added only for KR, JP and TW. More values might be added in the future, for other regions/countries and road types. Possible values:
|