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 ofRouteUpdateReason.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 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
.
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.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 }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 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 }56 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: