Turn-by-turn navigation

Turn-by-turn navigation provides real-time guidance along a calculated route. It informs the user about upcoming maneuvers and tracks progress along the route. To get started, add the Navigation module to your project and initialize a TomTomNavigation object. Refer to the Quickstart guide for setup instructions.

Starting navigation

Once the TomTomNavigation object is initialized, you can start navigation. Turn-by-turn navigation requires NavigationOptions , which must include an active RoutePlan.

A RoutePlan consists of a Route and the corresponding RoutePlanningOptions object. To learn how to plan a Route, see the Planning a route guide.

1
val routePlan = RoutePlan(route = route, routePlanningOptions = routePlanningOptions)

Next, use the prepared RoutePlan to create NavigationOptions, then start navigation by calling the start(NavigationOptions) method on your TomTomNavigation object.

1
tomTomNavigation.start(NavigationOptions(routePlan))

You can also stop the current navigation session manually using TomTomNavigation.stop(). This clears all related session data:

1
tomTomNavigation.stop()

Updating the route

Once TomTomNavigation is started, the active RoutePlan can be changed at any time—either manually or automatically by the navigation session.

To observe changes to the route during navigation, use the following listeners:

• RouteUpdatedListener2: triggered when the route is updated. See RouteUpdatedReason for more details.
• RouteAddedListener: triggered when a new route is added to the session.
• RouteRemovedListener: triggered when a route is removed from the session.
• ActiveRouteChangedListener: triggered when a new route is selected as the active one. The route must already be added to the session.

To manually update the active RoutePlan call:

1
tomTomNavigation.setActiveRoutePlan(routePlan)

1
val routeAddedListener =
2
    RouteAddedListener { route: Route, options: RoutePlanningOptions, reason: RouteAddedReason ->
3
        // YOUR CODE GOES HERE
4
    }
5
val routeRemovedListener =
6
    RouteRemovedListener { route: Route, reason: RouteRemovedReason ->
7
        // YOUR CODE GOES HERE
8
    }
9
val activeRouteChangedListener =
10
    ActiveRouteChangedListener { route: Route ->
11
        // YOUR CODE GOES HERE
12
    }
13
val routeUpdatedListener =
14
    RouteUpdatedListener2 { route: Route, reason: RouteUpdatedReason ->
15
        // YOUR CODE GOES HERE
16
    }
17
tomTomNavigation.addRouteAddedListener(routeAddedListener)
18
tomTomNavigation.addRouteRemovedListener(routeRemovedListener)
19
tomTomNavigation.addActiveRouteChangedListener(activeRouteChangedListener)
20
tomTomNavigation.addRouteUpdatedListener2(routeUpdatedListener)

To remove previously-added listeners, call the appropriate methods on the TomTomNavigation.

1
tomTomNavigation.removeRouteAddedListener(routeAddedListener)
2
tomTomNavigation.removeRouteRemovedListener(routeRemovedListener)
3
tomTomNavigation.removeActiveRouteChangedListener(activeRouteChangedListener)
4
tomTomNavigation.removeRouteUpdatedListener2(routeUpdatedListener)

Modifying the RoutePlanningOptions of the active route

1
val navigationSnapshot = tomTomNavigation.navigationSnapshot
2

3
val routeStopThatShouldBeSkipped =
4
    requireNotNull(navigationSnapshot!!.routes.first().waypoints.first()) {
5
        "Navigation should not be stopped and there should be a waypoint that the user wants to skip."
6
    }
7

8
// Create modified route planning options for the active route.
9
val modifiedRoutePlanningOptions =
10
    navigationSnapshot.currentActiveRoutePlanningOptions
11
        .skipRouteStop(routeStopThatShouldBeSkipped)
12

13
// Create a route planning callback that will change the active route plan if successfully planned.
14
val routePlanningCallback = object : RoutePlanningCallback {
15
    override fun onSuccess(result: RoutePlanningResponse) {
16
        // Choose a route, the first one is the best and usually fits the needs of the user.
17
        val chosenRoute = result.routes.first()
18

19
        tomTomNavigation.setActiveRoutePlan(
20
            RoutePlan(
21
                route = chosenRoute,
22
                routePlanningOptions = modifiedRoutePlanningOptions,
23
            ),
24
        )
25
    }
26

27
    override fun onFailure(failure: RoutingFailure) {
28
        // Handle failure
29
    }
30

31
    override fun onRoutePlanned(route: Route) {
32
        // Your code goes here
33
    }
34
}
35

36
// Plan a modified route
37
val cancellable = routePlanner.planRoute(modifiedRoutePlanningOptions, routePlanningCallback)

Route progress

Position-dependent fields that describe the user’s navigation status are collectively referred to as route progress data. Examples include the current position along the route (as an offset from the start), remaining travel time, and distance to the destination. These values are updated on every position update—typically once per second for each followed route. You can listen for changes to route progress. To listen for changes to route progress, set a ProgressUpdatedListener on the TomTomNavigation object. The ProgressUpdatedListener is triggered whenever the user’s progress along the Route changes. It provides a RouteProgressobject containing useful metrics such as estimated arrival time and remaining distance.

1
val progressUpdatedListener =
2
    ProgressUpdatedListener { progress: RouteProgress ->
3
        // YOUR CODE GOES HERE
4
    }
5
tomTomNavigation.addProgressUpdatedListener(progressUpdatedListener)

To remove a previously added listener, call TomTomNavigation.removeProgressUpdatedListener(ProgressUpdatedListener).

1
tomTomNavigation.removeProgressUpdatedListener(progressUpdatedListener)

Route deviations

During navigation, the TomTomNavigation object tracks the user’s position relative to the navigated routes and determines which ones are currently being followed. To listen for updates about route tracking changes, use the RouteTrackingStateUpdatedListener.

This listener provides a RouteTrackingState object, which contains lists of followed and unfollowed routes. It also indicates whether the driver has deviated from all tracked routes. To verify if the driver deviated from the route, check if the RouteTrackingState.hasDeviated property is true.

To listen for the route tracking updates, set a RouteTrackingStateUpdatedListener on the TomTomNavigation object.

1
val routeTrackingStateUpdatedListener =
2
    RouteTrackingStateUpdatedListener { routeTrackingState: RouteTrackingState ->
3
        // YOUR CODE GOES HERE
4
    }
5
tomTomNavigation.addRouteTrackingStateUpdatedListener(routeTrackingStateUpdatedListener)

To remove RouteTrackingStateUpdatedListener use the TomTomNavigation.removeRouteTrackingStateUpdatedListener(RouteTrackingStateUpdatedListener) method.

1
tomTomNavigation.removeRouteTrackingStateUpdatedListener(routeTrackingStateUpdatedListener)

If the driver deviates from the active route, navigation automatically enters free driving mode. In this mode, navigation temporarily operates without a RoutePlan. However, it automatically attempts to calculate a new route using the same cost model as the original. If successful, this new route becomes the active RoutePlan. You can find more details about automatic replanning in the Replanning on deviation section.

Route guidance

Route guidance combines maneuver instructions and spoken announcements that help users navigate along a route. Historically, the only source of voice announcements in the Navigation SDK has been turn-by-turn guidance, provided through the GuidanceUpdatedListener. The GuidanceUpdatedListener delivers maneuver instructions and announcements directly tied to those maneuvers. As the SDK has evolved, it now supports more audible use cases such as traffic jam alerts, better route proposals, and soon other contextual announcements that are not part of route-bound guidance. To support these broader scenarios, we introduced a new interface called the AnnouncementListener. The AnnouncementListener serves as a unified entry point for all audible announcements, making it easier for applications to receive, manage, and prioritize them while avoiding playback collisions.

Comparison: GuidanceUpdatedListener vs AnnouncementListener

GuidanceUpdatedListener

During navigation, TomTomNavigation generates guidance updates after each location change. These updates include upcoming maneuver instructions, the distance to the next maneuver, and announcements when the distance is within a triggerable range. All updates are sent to a GuidanceUpdatedListener. Note: Set the GuidanceUpdatedListener before starting the TomTomNavigation session.

The GuidanceUpdatedListener interface provides three callback methods:

• onInstructionsChanged(List<GuidanceInstruction>) – Triggered when guidance instructions change. Each GuidanceInstruction describes a specific maneuver (e.g., Turn right, Keep left, Take the motorway).
• onAnnouncementGenerated(GuidanceAnnouncement, Boolean) – Triggered when an announcement is generated.

A GuidanceAnnouncement contains a message, geographic location, and distance to the instruction point. The shouldPlay flag indicates whether announcement should be triggered according to guidelines.

• onDistanceToNextInstructionChanged(Distance, List<GuidanceInstruction>, InstructionPhase) – Triggered whenever the distance to the next instruction changes. It provides:
  • The current distance to the next maneuver (in meters)
  • The list of upcoming instructions
  • The current InstructionPhase

1
val guidanceUpdatedListener =
2
    object : GuidanceUpdatedListener {
3
        override fun onInstructionsChanged(instructions: List<GuidanceInstruction>) {
4
            // YOUR CODE GOES HERE
5
        }
6

7
        override fun onAnnouncementGenerated(
8
            announcement: GuidanceAnnouncement,
9
            shouldPlay: Boolean,
10
        ) {
11
            // YOUR CODE GOES HERE
12
        }
13

14
        override fun onDistanceToNextInstructionChanged(
15
            distance: Distance,
16
            instructions: List<GuidanceInstruction>,
17
            currentPhase: InstructionPhase,
18
        ) {
19
            // YOUR CODE GOES HERE
20
        }
21
    }
22
tomTomNavigation.addGuidanceUpdatedListener(guidanceUpdatedListener)

To remove a previously added GuidanceUpdatedListener, use the TomTomNavigation.removeGuidanceUpdatedListener(GuidanceUpdatedListener) method.

1
tomTomNavigation.removeGuidanceUpdatedListener(guidanceUpdatedListener)

To change the language used for guidance instructions, set the TomTomNavigation.preferredLanguage property:

1
tomTomNavigation.preferredLanguage = Locale.FRANCE

You can retrieve the current language using the TomTomNavigation.language property.

AnnouncementListener

During active guidance, TomTomNavigation generates maneuver instructions and warnings (such as traffic jam alerts). In free driving mode, it generates only warnings. All of these are delivered as audio announcements. These announcements are sent to a AnnouncementListener at a time when announcements should be played. Note: Set the AnnouncementListener before starting the TomTomNavigation session.

The AnnouncementListener interface provides one callback method:

• onAnnouncementsGenerated(announcements: List<Announcement>) – Triggered when announcements that should be played have been generated.

1
val announcementListener =
2
    object : AnnouncementListener {
3
        override fun onAnnouncementsGenerated(announcements: List<Announcement>) {
4
            // YOUR CODE GOES HERE
5
        }
6
    }
7
tomTomNavigation.addAnnouncementListener(announcementListener)

To remove a previously added AnnouncementListener, use the TomTomNavigation.removeAnnouncementListener(AnnouncementListener) method.

1
tomTomNavigation.removeAnnouncementListener(announcementListener)

Announcement types

TomTomNavigation generates multiple types of announcements, including guidance announcements, better route proposals, and traffic jam alerts.

Each announcement is represented by a subtype of the Announcement class. This allows you to perform type-specific handling of announcements.

1
announcements.forEach { announcement ->
2
    when (announcement) {
3
        is BetterRouteProposalAnnouncement -> {
4
            // Handle better route proposal announcement
5
        }
6

7
        is TrafficJamAnnouncement -> {
8
            // Handle traffic jam announcement
9
        }
10

11
        else -> {
12
            // Handle other types of announcements
13
        }
14
    }
15
}

Every announcement includes Message that can be either:

• VerbalMessage - a Message intended for text-to-speech synthesis.
• Alert - a Message with no text to be spoken, typically used to trigger a sound.

In addition, some announcements provide extra information that can be used to enhance the user experience. For example, a BetterRouteProposalAnnouncement includes the routeId of the proposed better route, which can be used to suppress announcements for the previously declined better route.

Audio collision management

When multiple announcements are generated simultaneously, it is crucial to manage audio playback effectively to ensure clarity and prevent overlapping announcements. TomTomNavigation incorporates an audio collision management system that prioritizes announcements based on their importance and timing.

It is possible to choose between two strategies for handling audio collisions:

• NoResolution - No resolution is applied to announcement conflicts, thereby making the AnnouncementListener return all announcements that should be played, without any filtering and in no particular order.

• PriorityCancellation - Announcements are prioritized based on their importance, and lower-priority announcements are canceled if they conflict with higher-priority ones.

  Alerts are excluded from this strategy and are always delivered to the AnnouncementListener.

To set the desired strategy, use the TomTomNavigation.announcementConflictResolutionStrategy property:

1
tomTomNavigation.announcementConflictResolutionStrategy =
2
    AnnouncementConflictResolutionStrategy.PriorityCancellation

or

1
tomTomNavigation.announcementConflictResolutionStrategy =
2
    AnnouncementConflictResolutionStrategy.NoResolution

Migrate from GuidanceUpdatedListener to AnnouncementListener

To migrate to the AnnouncementListener from the GuidanceUpdatedListener, while leaving the other logic intact, you can use the following code:

1
fun GuidanceAnnouncement.toAnnouncementType(): AnnouncementType {
2
    return when (this) {
3
        is GuidanceAnnouncement.Follow -> AnnouncementType.GuidanceFollow
4
        is GuidanceAnnouncement.Main -> AnnouncementType.GuidanceMain
5
        is GuidanceAnnouncement.Early -> AnnouncementType.GuidanceEarly
6
        is GuidanceAnnouncement.Confirmation -> AnnouncementType.GuidanceConfirmation
7
        is GuidanceAnnouncement.FarAway -> AnnouncementType.GuidanceFarAway
8
        else -> throw IllegalArgumentException("Unsupported announcement type: $this")
9
    }
10
}
11

12
fun GuidanceAnnouncement.toLegacyGuidanceAnnouncement(): LegacyGuidanceAnnouncement {
13
    return LegacyGuidanceAnnouncement(
14
        id = this.id,
15
        announcementType = this.toAnnouncementType(),
16
        ssmlMessage = this.message.ssmlMessage,
17
        language = this.message.language,
18
    )
19
}
20

21
announcements
22
    .filterIsInstance<GuidanceAnnouncement>()
23
    .map { it.toLegacyGuidanceAnnouncement() }
24
    .let { /* use the same logic from the GuidanceUpdatedListener */ }

Lane-level guidance

TomTomNavigation has built-in support for generating lane guidance. Lane guidance is generated for each LaneSection object in a Route.

You can learn more about how to request a route with a LaneSection by reading the Route sections guide.

The LaneGuidance object includes:

• lanes - A left‑to‑right list of Lane objects, each representing one physical lane on the road. Each Lane contains:
  • directions
    • A list of possible driving directions available from the lane.
    • Examples: LEFT, STRAIGHT, RIGHT, etc.
    • At least one direction is expected.
  • follow
    • The recommended direction to follow if this lane is part of the active route.
    • null means the lane is not recommended.
    • If not null, the driver should follow that direction from this lane.
  • More than one lane can be marked as recommended.

Example:

1
// Only a left arrow, not recommended
2
Lane(
3
    directions = listOf(Direction.LEFT),
4
    follow = null,
5
)
6

7
// Straight + right arrows, straight is recommended
8
Lane(
9
    directions = listOf(Direction.STRAIGHT, Direction.RIGHT),
10
    follow = Direction.STRAIGHT,
11
)

• laneSeparators - A list of separators (e.g., dashed lines, solid barriers) shown between and around lanes. For n lanes, n + 1 separators are provided. Each separator is shared between two lanes or marks the road edge.
• routeOffset - The distance from the start of the route to where this lane guidance begins.
• length - The distance over which this lane guidance is valid.

The following are the possible states for each individual lane guidance arrow

Highlighted SLG arrow represents the direction required by the current route. Greyed-out arrows represent alternative directions that should not be taken.

The following schematic images help illustrate Lane‑level Guidance:

• The right image shows the schematic lane arrow display, highlighting which lanes are part of the recommended maneuver. In this example, three right-turn lanes are highlighted.
• The left image provides a realistic visualization of the road ahead. It shows a highway segment with clearly visible lanes and lane separators, helping developers understand how the guidance maps to actual road structures.

The generated LaneGuidance is sent to LaneGuidanceUpdatedListener. LaneGuidanceUpdatedListener has two methods:

• onLaneGuidanceStarted(LaneGuidance) - Triggered when lane guidance appears.
• onLaneGuidanceEnded(LaneGuidance) - Triggered when lane guidance disappears.

The onLaneGuidanceStarted(LaneGuidance) callback is only triggered when all of the following conditions are met:

• A maneuver is approaching (e.g., turn, merge, exit)
• More than one lane is available (lanes.size > 1)
• Each lane includes at least one direction
• At least one lane has a follow direction
• Not all lanes have a follow direction

If these conditions are not met, the callback is not triggered.

1
val laneGuidanceUpdatedListener =
2
    object : LaneGuidanceUpdatedListener {
3
        override fun onLaneGuidanceStarted(laneGuidance: LaneGuidance) {
4
            // laneGuidance.lanes is guaranteed to be non‑empty
5
            // YOUR CODE GOES HERE
6
        }
7

8
        override fun onLaneGuidanceEnded(laneGuidance: LaneGuidance) {
9
            // YOUR CODE GOES HERE
10
        }
11
    }
12
tomTomNavigation.addLaneGuidanceUpdatedListener(laneGuidanceUpdatedListener)

To remove a previously added LaneGuidanceUpdatedListener, use the TomTomNavigation.removeLaneGuidanceUpdatedListener(LaneGuidanceUpdateListener) method.

1
tomTomNavigation.removeLaneGuidanceUpdatedListener(laneGuidanceUpdatedListener)

Arrival experience

The Navigation module uses the generated RouteProgress to detect when the user arrives at their destination. When arrival is detected, the DestinationArrivalListener is triggered. This means that the ArrivalDetectionEngine has confirmed arrival.

Note: Even after arrival is detected, navigation remains in turn-by-turn mode until it is manually stopped.

To listen for arrival events, register a DestinationArrivalListener.

1
val destinationArrivalListener =
2
    DestinationArrivalListener {
3
        // YOUR CODE GOES HERE
4
    }
5
tomTomNavigation.addDestinationArrivalListener(destinationArrivalListener)

To remove a previously registered DestinationArrivalListener, use:

1
tomTomNavigation.removeDestinationArrivalListener(destinationArrivalListener)

Waypoint arrival

The active Route may include intermediate stops that the driver intends to visit before reaching the final destination. These intermediate stops, known as waypoints, are listed in routeStops as instances of the RouteStop class. You can find more details on waypoints in the Waypoints and custom routes guide.

Arriving at a waypoint is detected in three phases: Approaching, Visiting, and Departing. When a waypoint’s arrival state changes, the WaypointArrivalListener is triggered. This means the ArrivalDetectionEngine has successfully detected arrival at the waypoint. It determines arrival by verifying whether the distance along the route is within the arrival radius of the waypoint. The distance threshold is:

• 100 meters on motorways
• 50 meters on other roads

A waypoint is automatically marked as departed when:

• The driver is on an active route and has increased the distance along the route by the distance threshold.
• The driver deviates from the active route, moves away from the waypoint by more than the distance threshold in a straight line.

To listen for waypoint arrival and departure events, implement and register a WaypointArrivalListener:

1
val waypointArrivalListener =
2
    object : WaypointArrivalListener {
3
        override fun onWaypointArrived(
4
            waypoint: RouteStop,
5
            route: Route,
6
        ) {
7
            // YOUR CODE GOES HERE
8
        }
9

10
        override fun onWaypointDeparted(
11
            waypoint: RouteStop,
12
            route: Route,
13
        ) {
14
            // YOUR CODE GOES HERE
15
        }
16
    }
17
tomTomNavigation.addWaypointArrivalListener(waypointArrivalListener)

To remove a previously added WaypointArrivalListener, use the following code:

1
tomTomNavigation.removeWaypointArrivalListener(waypointArrivalListener)

You can also manually mark a waypoint as visited independently of the ArrivalDetectionEngineby calling:

1
tomTomNavigation.departFromWaypoint(waypoint)

This method throws an exception if the specified waypoint has not yet been marked as arrived or has no effect if it has already been departed from.

If the operation succeeds, the WaypointArrivalListener.onWaypointDeparted callback is triggered. This signifies completion of arrival detection for the specific waypoint. Navigation then switches to detecting arrival for the next waypoint, if one exists.

Next steps

Since you have learned how to work with turn-by-turn navigation, here are recommendations for the next steps:

• Planning a route
• Voice instructions (Text-To-Speech)
• Turn-by-turn instructions