Guidance

The guidance parameter enables turn-by-turn navigation instructions in route responses. When specified, the calculated route includes detailed maneuvers, road names, distances, and optional phonetic pronunciations for voice guidance.

Basic usage

Request guidance instructions with default settings:

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

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    guidance: {
        type: 'coded'
    }
});

Configuration

Instruction format

Currently only 'coded' format is supported:

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    guidance: {
        type: 'coded',
    }
});

Phonetic transcriptions

Include phonetic pronunciations for street names to enable accurate voice guidance:

// International Phonetic Alphabet (default)
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    guidance: {
        type: 'coded',
        phonetics: 'IPA'
    }
});

// Language-specific phonetic representation
const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    guidance: {
        type: 'coded',
        phonetics: 'LHP'
    }
});

Available phonetic formats:

• IPA - International Phonetic Alphabet (default)
• LHP - Language-specific phonetic representation

Road shield references

Include references to road sign images for visual display:

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    guidance: {
        type: 'coded',
        roadShieldReferences: 'all'
    }
});

When enabled, the response includes references to road shield images that can be fetched from the TomTom Road Shield API.

Accessing guidance data

Route instructions are included in the response properties:

const route = await calculateRoute({
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
    guidance: {
        type: 'coded'
    }
});

// Access guidance instructions
const instructions = route.features[0].properties.guidance?.instructions;

What each instruction carries

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

Name fields are TextWithPhonetics: text plus, when phonetics were requested, a phonetic string already transcribed in the requested alphabet and a phoneticLanguageCode.

instructions?.forEach((instruction) => {
    console.log(instruction.message);
    console.log(instruction.nextRoadInfo.streetName?.phonetic);
});

API reference

For complete documentation of all route guidance properties and types, see the GuidanceParams API Reference.

Related guides and examples

Related guides

• Routing Quickstart - Getting started with route calculation
• Route Planning Parameters - Comprehensive route planning with configuration options
• Route Object - Understanding route structure

Related examples

• Route with guidance arrows - Displaying routes with turn-by-turn instructions