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, seeRouteUpdateReason
. - 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 aRouteAddedReason.ManuallyUpdated
reason provided in theRouteAddedListener
.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 theupdate 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 }56 override fun onAnnouncementGenerated(announcement: GuidanceAnnouncement, shouldPlay: Boolean) {7 /* YOUR CODE GOES HERE */8 }910 override fun onDistanceToNextInstructionChanged(11 distance: Distance,12 instructions: List<GuidanceInstruction>,13 currentPhase: InstructionPhase14 ) {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 }56 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 }56 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: