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, the RoutePlan you’re following can be changed at any time; either manually or automatically by the navigation session.

The route changes during navigation are observed using:

• The RouteUpdatedListener - provides information about the route updates that do not change the route geometry, see RouteUpdateReason.
• The RouteAddedListener - provides information about the new route being added to the navigation session.
• The RouteRemovedListener - provides information about the route being removed from the navigation session.
• The ActiveRouteChangedListener - provides information about the new route being applied as an active route; the route must have been previously added to the session.

You can manually change the RoutePlan you’re following at any time.

tomTomNavigation.update(NavigationOptions(routePlan))

A manual RoutePlan update results in a RouteAddedReason.ManuallyUpdated reason provided in the RouteAddedListener.

Other reasons can occur after route replanning.

1val routeAddedListener = RouteAddedListener { route: Route, reason: RouteAddedReason ->
2    /* YOUR CODE GOES HERE */
3}
4val routeRemovedListener = RouteRemovedListener { route: Route, reason: RouteRemovedReason ->
5    /* YOUR CODE GOES HERE */
6}
7val activeRouteChangedListener = ActiveRouteChangedListener { route: Route ->
8    /* YOUR CODE GOES HERE */
9}
10val routeUpdatedListener = RouteUpdatedListener { route: Route, updateReason: RouteUpdateReason ->
11    /* YOUR CODE GOES HERE */
12}
13tomTomNavigation.addRouteAddedListener(routeAddedListener)
14tomTomNavigation.addRouteRemovedListener(routeRemovedListener)
15tomTomNavigation.addActiveRouteChangedListener(activeRouteChangedListener)
16tomTomNavigation.addRouteUpdatedListener(routeUpdatedListener)

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

1tomTomNavigation.removeRouteAddedListener(routeAddedListener)
2tomTomNavigation.removeRouteRemovedListener(routeRemovedListener)
3tomTomNavigation.removeActiveRouteChangedListener(activeRouteChangedListener)
4tomTomNavigation.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

During the navigation, the TomTomNavigation tracks your position relative to the navigated routes and provides information which ones are followed. To listen for such updates, use the RouteTrackingStateUpdatedListener.

The RouteTrackingState object is an argument provided by the RouteTrackingStateUpdatedListener. It contains a list of the followed and unfollowed routes. Additionally, it tells when the driver deviates from all the routes. To verify if the driver deviated from the route, check if the RouteTrackingState.hasDeviated property is true.

To listen to the route tracking updates, set RouteTrackingStateUpdatedListener to the TomTomNavigation object.

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

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

tomTomNavigation.removeRouteTrackingStateUpdatedListener(routeTrackingStateUpdatedListener)

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. Note that GuidanceUpdatedListener should be set before TomTomNavigation is started.

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.preferredLanguage property.

tomTomNavigation.preferredLanguage = Locale.FRANCE

Current language can be retrieved by TomTomNavigation.language property.

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 DestinationArrivalListener. 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.

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

DestinationArrivalListener can be removed as below.

tomTomNavigation.removeDestinationArrivalListener(destinationArrivalListener)

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 RouteStop. 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 onWaypointArrived(waypoint: RouteStop, route: Route) {
3        /* YOUR CODE GOES HERE */
4    }
5
6    override fun onWaypointDeparted(waypoint: RouteStop, route: Route) {
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