Turn-by-turn navigation

Navigation SDK for Android is only available upon request. Contact us to get started.

Turn-by-turn navigation is navigation along a calculated route. It provides information about the next maneuvers and the progress along the current route. To begin, add the navigation module to your project and set up a TomTomNavigation object. You can learn how to do this in the Quickstart guide.

Starting navigation

Once the TomTomNavigation object is initialized, you can start navigation. Turn-by-turn navigation requires NavigationOptions for navigation to follow. NavigationOptions encapsulate an active RoutePlan.

A RoutePlan consists of a Route and the RoutePlanningOptions objects used for planning it. You can learn more about how to plan a Route in the Planning a route guide.

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

Now you can use the prepared RoutePlan to create NavigationOptions and start navigation. To do this, call the start(NavigationOptions) method on your TomTomNavigation object.

tomTomNavigation.start(NavigationOptions(routePlan))

TomTomNavigation also supports manually stopping navigation. The TomTomNavigation.stop() method stops the current navigation session and clears all data related to it.

tomTomNavigation.stop()

If navigation was not started, the stop method will have no effect.

Updating the route

Once TomTomNavigation is started, you can change the RoutePlan you’re following at any time.

tomTomNavigation.update(NavigationOptions(routePlan))

Navigation RoutePlan updates are observed using the RouteUpdatedListener callback.

If it is registered on the TomTomNavigation object, it reports when there is a successful RoutePlan update.

The provided Route parameter is then the new Route that navigation follows. The RouteUpdateReason parameter indicates why the route was updated.

A manual RoutePlan update results in an updated reason of RouteUpdateReason.Manual.

Other reasons can occur after route replanning.

1val routeUpdatedListener =
2    RouteUpdatedListener { route: Route, updateReason: RouteUpdateReason ->
3        when (updateReason) {
4            RouteUpdateReason.Manual -> { /* YOUR CODE GOES HERE */
5            }
6            RouteUpdateReason.Refresh -> { /* YOUR CODE GOES HERE */
7            }
8            RouteUpdateReason.Blockage -> { /* YOUR CODE GOES HERE */
9            }
10            RouteUpdateReason.BetterFound -> { /* YOUR CODE GOES HERE */
11            }
12            RouteUpdateReason.Deviation -> { /* YOUR CODE GOES HERE */
13            }
14            RouteUpdateReason.Increment -> { /* YOUR CODE GOES HERE */
15            }
16            RouteUpdateReason.OutOfRange -> { /* YOUR CODE GOES HERE */
17            }
18        }
19    }
20tomTomNavigation.addRouteUpdatedListener(routeUpdatedListener)

To remove a previously-added listener, call TomTomNavigation.removeRouteUpdatedListener(RouteUpdatedListener).

tomTomNavigation.removeRouteUpdatedListener(routeUpdatedListener)

Route progress

The position-dependent data fields are collectively known as the "Route Progress" data. Examples of these data are position on route (offset from the beginning) and remaining travel time. These fields are updated on every position update roughly once per second for every followed route in the system. You can listen for changes to route progress. To listen for changes, set ProgressUpdatedListener to the TomTomNavigation object. ProgressUpdatedListener is triggered whenever the user’s progress along the Route is changed. It provides the current RouteProgress, which contains, among other things, the arrival time and the remaining distance along the route.

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

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

tomTomNavigation.removeProgressUpdatedListener(progressUpdatedListener)

Route deviations

The Navigation module detects when the user has diverged from the navigated route. Whenever a deviation is detected, the RouteDeviationListener is invoked with a location and a route. The GeoLocation provided by the callback is the localization of that route deviation. The Route parameter is the Route from which the user deviated. You can listen for route deviations. To listen to route deviations, set RouteDeviationListener to the TomTomNavigation object.

1val routeDeviationListener =
2    RouteDeviationListener { location: GeoLocation, route: Route ->
3        /* YOUR CODE GOES HERE */
4    }
5tomTomNavigation.addRouteDeviationListener(routeDeviationListener)

To remove RouteDeviationListener use the TomTomNavigation.removeRouteDeviationListener(RouteDeviationListener) method.

tomTomNavigation.removeRouteDeviationListener(routeDeviationListener)

If the driver does deviate from the route, navigation enters free driving mode. This means that navigation runs without a RoutePlan. The RoutePlan automatically replans using the same cost model as used in the original RoutePlan. You can find more details about automatic replanning in the Replanning on deviation section.

You can disable automatic replanning and provide a new RoutePlan manually using the update method.

Route guidance

The combination of maneuver instructions and maneuver announcements is called Route Guidance.

During navigation, TomTomNavigation generates a guidance update after each location change. Generated guidance consists of the next instructions, the distance to a maneuver, and an announcement if the distance is within a suitable range. The generated guidance is then sent to GuidanceUpdatedListener.

GuidanceUpdatedListener has three methods:

• onInstructionsChanged(List<GuidanceInstruction>) - This reports a change to guidance instructions. GuidanceInstruction contains information describing a maneuver, e.g., 'Turn right', 'Keep left', 'Take the Motorway'.
• onAnnouncementGenerated(GuidanceAnnouncement, Boolean) - This is triggered when an announcement is generated.

The GuidanceAnnouncement is an announcement point with its own message, location, and distance to the instruction point. The shouldPlay flag indicates whether announcement should be triggered according to guidelines.

• onDistanceToNextInstructionChanged(Distance, List<GuidanceInstruction>, InstructionPhase) - This is called with each change of distance to the instruction. The first parameter is the distance in meters to the instruction. The second parameter provides the next instructions. The third parameter is the current triggering phase of the instruction.

1val guidanceUpdatedListener = object : GuidanceUpdatedListener {
2    override fun onInstructionsChanged(instructions: List<GuidanceInstruction>) {
3        /* YOUR CODE GOES HERE */
4    }
5
6    override fun onAnnouncementGenerated(announcement: GuidanceAnnouncement, shouldPlay: Boolean) {
7        /* YOUR CODE GOES HERE */
8    }
9
10    override fun onDistanceToNextInstructionChanged(
11        distance: Distance,
12        instructions: List<GuidanceInstruction>,
13        currentPhase: InstructionPhase
14    ) {
15        /* YOUR CODE GOES HERE */
16    }
17}
18tomTomNavigation.addGuidanceUpdatedListener(guidanceUpdatedListener)

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

tomTomNavigation.removeGuidanceUpdatedListener(guidanceUpdatedListener)

Instruction language can be changed by updating TomTomNavigation.language property.

tomTomNavigation.language = Locale.FRANCE

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 - This is an object that consists of a list with directions and an optional lane direction that the driver should follow.
• laneSeparators - This is a list of lane separators.
• routeOffset - This is the distance in meters from the start of the route to the start of the lanes.
• length - This is the length in meters of the lane section.

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

• onLaneGuidanceStarted(LaneGuidance) - This is triggered when lane guidance appears.
• onLaneGuidanceEnded(LaneGuidance) - This is triggered when lane guidance disappears.

1val laneGuidanceUpdatedListener = object : LaneGuidanceUpdatedListener {
2    override fun onLaneGuidanceStarted(laneGuidance: LaneGuidance) {
3        /* YOUR CODE GOES HERE */
4    }
5
6    override fun onLaneGuidanceEnded(laneGuidance: LaneGuidance) {
7        /* YOUR CODE GOES HERE */
8    }
9}
10tomTomNavigation.addLaneGuidanceUpdatedListener(laneGuidanceUpdatedListener)

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

tomTomNavigation.removeLaneGuidanceUpdatedListener(laneGuidanceUpdatedListener)

Arrival experience

The Navigation module uses the generated RouteProgress to detect that the user has arrived at the destination. Once arrival is detected it triggers DestinationReachedListener. This means that the ArrivalDetectionEngine has detected an arrival.

At that point navigation continues to be in turn-by-turn mode until it’s stopped or switched into free driving mode.

1val destinationReachedListener = DestinationReachedListener {
2    /* YOUR CODE GOES HERE */
3}
4tomTomNavigation.addDestinationReachedListener(destinationReachedListener)

DestinationReachedListener can be removed as below.

tomTomNavigation.removeDestinationReachedListener(destinationReachedListener)

Waypoint arrival

The Route being followed can contain route stops that the driver wants to visit before arriving at the destination. These stops, called waypoints, are included in routeStops as instances of the type Waypoint. You can find more details on waypoints in the Waypoints and custom routes guide.

The Navigation module uses the generated RouteProgress to detect the state of user arrival at a waypoint. Once waypoint arrival state change is detected it triggers WaypointArrivalListener. This means that the ArrivalDetectionEngine has successfully detected an arrival at the waypoint.

1val waypointArrivalListener = object : WaypointArrivalListener {
2    override fun onWaypointReached(waypoint: Waypoint) {
3        /* YOUR CODE GOES HERE */
4    }
5
6    override fun onWaypointVisited(waypoint: Waypoint) {
7        /* YOUR CODE GOES HERE */
8    }
9}
10tomTomNavigation.addWaypointArrivalListener(waypointArrivalListener)

WaypointArrivalListener can be removed as shown in the following figure.

tomTomNavigation.removeWaypointArrivalListener(waypointArrivalListener)

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