Guidance

guidance adds turn-by-turn instructions to each route: maneuvers, ready-made instruction text, road names, road shields and junction layouts.

The demo below requests guidance for a route through central Amsterdam. The routing module draws an arrow at every turn, and the panel lists each instruction with the lanes to take.

Basic usage

'coded' is the only instruction format:

1
import { calculateRoute } from '@tomtom-org/maps-sdk/services';
2

3
const routes = await calculateRoute({
4
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
5
    guidance: { type: 'coded' }
6
});
7

8
const instructions = routes.features[0].properties.guidance?.instructions;

• Requesting guidance also returns lane guidance in the lanes section, unless a sectionTypes list leaves lanes out. No request returns lanes without guidance. To find the section leading to an instruction, use getInstructionLanes.
• On the map, RoutingModule draws the instructions as arrows. See Displaying guidance on map.

What each instruction carries

• message – The ready-made instruction text, for example 'Turn right onto Damrak'. The service generates and localises it in the request’s language, so a turn list needs no translation table.
• maneuver – The maneuver code, for example 'TURN_RIGHT'.
• maneuverPoint / pathPointIndex – Where the maneuver happens, as a [longitude, latitude] position and its index into the route’s geometry.coordinates. The point is the junction as the router names it, so it can sit a few metres off the sampled path.
• routeOffsetInMeters – Distance from the start of the route to the maneuver.
• maneuverView – The junction layout. onRouteAngle is the direction the route takes, and offRouteAngles are the ones it passes up. Both are relative directions ('STRAIGHT', 'SLIGHT_RIGHT', 'BACK', …), not degrees, but enough to draw a junction diagram.
• roundaboutType – 'REGULAR' or 'SMALL', on roundabout maneuvers.
• sideRoads – Roads joining the route near the maneuver, each with its side ('LEFT' | 'RIGHT' | 'LEFT_AND_RIGHT'), offsetFromManeuverInMeters and isDrivable.
  • A non-drivable side road can’t be taken by mistake, but it still belongs in a junction diagram.
• nextRoadInfo / previousRoadInfo – The road after and before the maneuver, with streetName, roadShields and an ISO 3166-1 alpha-3 countryCode.
• signpost, tollgateName, countryCrossingFromName / countryCrossingToName – Present on the maneuvers they apply to.

Name fields (street names, road numbers, signpost exits, intersections, tollgates and countries) are InstructionText objects, carrying the name as text:

1
instructions?.forEach((instruction) => {
2
    console.log(instruction.message, instruction.nextRoadInfo.streetName?.text);
3
});

Road shield references

Road shield images come from the TomTom Road Shield API. Each instruction carries roadShieldReferences for the instruction and signpostRoadShieldReferences for its signpost. roadShieldAtlasReference is the base URL they resolve against.

API reference

• GuidanceParams – The request parameter
• Instruction – Every field of an instruction

Related guides and examples

Related guides

• Routing quickstart – Getting started with route calculation
• Route planning parameters – Every other option
• Route object – Where guidance sits in the response

Related examples

• Route with guidance – A route with its guidance arrows, and its instructions with lane signs