Turn-by-turn navigation

VERSION 0.3.34
PUBLIC PREVIEW

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

Turn-by-turn navigation is navigation along a provided route. It provides information about the next maneuvers and the progress along the current route. First, add the navigation module to your project and set up a TomTomNavigation object. Read 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 a RoutePlan for navigation to follow. A RoutePlan consists of a Route and the RoutingOptions objects used for planning it. More details on how to plan a Route can be found in the Planning a route guide.

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

Now the prepared RoutePlan can be used to start navigation. To do this, call the start(RoutePlan) method on your TomTomNavigation object.

tomTomNavigation.start(routePlan)

center

Starting navigation is an asynchronous operation. You can pass an optional callback which will be triggered after the operation is finished, whether it succeeds or not.

1tomTomNavigation.start(
2 routePlan,
3 object : NavigationStartedCallback {
4 override fun onNavigationStarted() {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: NavigationStartError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

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 has not been started, the stop method will have no effect.

Updating the route

Once TomTomNavigation is started, you can change the RoutePlan being followed at any time.

tomTomNavigation.update(routePlan)

Navigation RoutePlan updates can be observed using the OnRouteUpdatedListener callback. If it is registered on the TomTomNavigation object, it reports when there has been a successful RoutePlan update. The provided Route parameter is then the new Route that navigation will follow. The RouteUpdateReason parameter indicates why the route was updated. You can also pass a dedicated callback directly into the TomTomNavigation.update() method to be notified of the outcome.

1tomTomNavigation.update(
2 routePlan,
3 object : RouteUpdatedCallback {
4 override fun onRouteUpdated(route: Route, routeUpdateReason: RouteUpdateReason) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: RouteUpdateError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

A manual RoutePlan update will result in an updated reason of RouteUpdateReason.MANUAL. Other reasons can occur after route replanning.

1val onRouteUpdatedListener =
2 OnRouteUpdatedListener { route: Route, updateReason: RouteUpdateReason ->
3 when (updateReason) {
4 RouteUpdateReason.MANUAL -> { /* YOUR CODE GOES HERE */ }
5 RouteUpdateReason.REFRESH -> { /* YOUR CODE GOES HERE */ }
6 RouteUpdateReason.UNREACHABLE -> { /* YOUR CODE GOES HERE */ }
7 RouteUpdateReason.BETTER_FOUND -> { /* YOUR CODE GOES HERE */ }
8 RouteUpdateReason.DEVIATION -> { /* YOUR CODE GOES HERE */ }
9 }
10 }
11tomTomNavigation.addOnRouteUpdatedListener(onRouteUpdatedListener)

To remove a previously-added listener, call TomTomNavigation.removeOnRouteUpdatedListener(onRouteUpdatedListener).

tomTomNavigation.removeOnRouteUpdatedListener(onRouteUpdatedListener)

Route progress

The position-dependent data fields are collectively known as the "Route Progress" data. Some examples 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 do so, set OnProgressUpdateListener to the TomTomNavigation object. OnProgressUpdateListener is triggered whenever the user’s progress along the Route has changed. It provides the current RouteProgress, which contains, among other things, the arrival time and the remaining distance along the route.

1val onProgressUpdateListener =
2 OnProgressUpdateListener { progress: RouteProgress -> /* YOUR CODE GOES HERE */
3 }
4tomTomNavigation.addOnProgressUpdateListener(onProgressUpdateListener)

To remove a previously-added listener, call TomTomNavigation.removeOnProgressUpdateListener(OnProgressUpdateListener).

tomTomNavigation.removeOnProgressUpdateListener(onProgressUpdateListener)

Route deviations

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

1val onRouteDeviationListener =
2 OnRouteDeviationListener { location: GeoLocation, route: Route -> /* YOUR CODE GOES HERE */ }
3tomTomNavigation.addOnRouteDeviationListener(onRouteDeviationListener)

To remove OnRouteDeviationListener use the TomTomNavigation.removeOnRouteDeviationListener(OnRouteDeviationListener) method.

tomTomNavigation.removeOnRouteDeviationListener(onRouteDeviationListener)

If the driver does deviate from the route, navigation will enter free driving mode. This means that navigation will run without a RoutePlan. RoutePlan will be automatically replanned using the same cost model as in the original RoutePlan. More details about automatic replanning can be found in 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 known as 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 in a suitable range. The generated guidance is then sent to OnGuidanceUpdateListener. OnGuidanceUpdateListener has 3 methods:

1val onGuidanceUpdateListener = object : OnGuidanceUpdateListener {
2 override fun onInstructionsChanged(instructions: List<GuidanceInstruction>) {
3 /* YOUR CODE GOES HERE */
4 }
5
6 override fun onAnnouncementGenerated(announcement: GuidanceAnnouncement) {
7 /* YOUR CODE GOES HERE */
8 }
9
10 override fun onDistanceToCurrentInstructionChanged(
11 distance: Distance,
12 instructions: List<GuidanceInstruction>
13 ) {
14 /* YOUR CODE GOES HERE */
15 }
16}
17tomTomNavigation.addOnGuidanceUpdateListener(onGuidanceUpdateListener)

To remove a previously-added OnGuidanceUpdateListener use the TomTomNavigation.removeOnGuidanceUpdateListener(OnGuidanceUpdateListener) method.

tomTomNavigation.removeOnGuidanceUpdateListener(onGuidanceUpdateListener)

Lane level guidance

TomTomNavigation has built-in support to generate lane guidance. Lane guidance is generated for each LaneSection object in a Route. More details on how to request a route with a LaneSection are described in the Route sections guide.

The LaneGuidance object consists of:

  • lanes - An object that consists of a list with directions and an optional lane direction the driver should follow.
  • laneSeparators - A list of lane separators.
  • routeOffsetInMeters - The distance from the start of the route to the start of the lanes.
  • lengthInMeters - Length of the lane section.

The generated LaneGuidance is sent to OnLaneGuidanceUpdateListener. OnLaneGuidanceUpdateListener has 2 methods:

1val onLaneGuidanceUpdateListener = object : OnLaneGuidanceUpdateListener {
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.addOnLaneGuidanceUpdatedListener(onLaneGuidanceUpdateListener)

To remove a previously-added OnLaneGuidanceUpdateListener, use the TomTomNavigation.removeOnLaneGuidanceUpdatedListener(OnLaneGuidanceUpdateListener) method.

tomTomNavigation.removeOnLaneGuidanceUpdatedListener(onLaneGuidanceUpdateListener)

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 OnDestinationReachedListener. This means that the ArrivalDetectionEngine has detected an arrival. At that point navigation will continue to be in turn-by-turn mode until stopped or switched into free driving mode.

1val onDestinationReachedListener = OnDestinationReachedListener {
2 /* YOUR CODE GOES HERE */
3}
4tomTomNavigation.addOnDestinationReachedListener(onDestinationReachedListener)

OnDestinationReachedListener can be removed as below.

tomTomNavigation.removeOnDestinationReachedListener(onDestinationReachedListener)

Waypoint arrival

The Route to follow can contain route stops that the driver wants to visit before arriving at the destination. These stops, called waypoints, will be included in routePoints as instances of the type Waypoint. More details on waypoints can be found in the Waypoints and custom routes guide. The Navigation module uses the generated RouteProgress to detect that the user has arrived at a waypoint. Once waypoint arrival is detected it triggers OnWaypointVisitedListener. This means that the ArrivalDetectionEngine has detected an arrival at the waypoint.

1val onWaypointVisitedListener = OnWaypointVisitedListener {
2 /* YOUR CODE GOES HERE */
3}
4tomTomNavigation.addOnWaypointVisitedListener(onWaypointVisitedListener)

OnWaypointVisitedListener can be removed as below.

tomTomNavigation.removeOnWaypointVisitedListener(onWaypointVisitedListener)