Guidance

VERSION 0.41.1 PUBLIC PREVIEW

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:

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

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

Configuration

Instruction Format

Currently only 'coded' format is supported:

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

Phonetic Transcriptions

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

1
// International Phonetic Alphabet (default)
2
const route = await calculateRoute({
3
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
4
    guidance: {
5
        type: 'coded',
6
        phonetics: 'IPA'
7
    }
8
});
9

10
// Language-specific phonetic representation
11
const route = await calculateRoute({
12
    locations: [[4.9041, 52.3676], [2.3522, 48.8566]],
13
    guidance: {
14
        type: 'coded',
15
        phonetics: 'LHP'
16
    }
17
});

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:

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

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:

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

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

API Reference

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

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

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