Starting navigation

VERSION 0.32.0

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

This guide explains how to start turn-by-turn navigation and retrieve route progress information such as the remaining travel time and travelled distance.

Project setup

Configure the project as described in the Project setup guide. Then add the following dependencies to the build.gradle file of your application module and synchronize the project.

1dependencies {
  def version = "0.32.0"
  implementation "com.tomtom.sdk.location:provider-simulation:$version"
  implementation "com.tomtom.sdk.navigation:navigation-online:$version"
  implementation "com.tomtom.sdk.navigation:route-replanner-online:$version"
  implementation "com.tomtom.sdk.routing:route-planner-online:$version"
7}

Before starting navigation with a route, you need to plan the route and set up a location provider to receive location updates along the route.

First, plan a Route between two locations using RoutePlanningOptions. Refer to the Planning a route guide if you want to learn more about how to plan a Route.

1routePlanner = OnlineRoutePlanner.create(context = this, apiKey = TOMTOM_API_KEY)
2val amsterdam = GeoPoint(latitude = 52.37616, longitude = 4.90828)
3val rotterdam = GeoPoint(latitude = 51.90546, longitude = 4.46662)
4val itinerary = Itinerary(origin = amsterdam, destination = rotterdam)
5routePlanningOptions = RoutePlanningOptions(
6    itinerary = itinerary,
7    guidanceOptions = GuidanceOptions(progressPoints = ProgressPoints.All),
8    vehicle = Vehicle.Car()
9)
10routePlanner.planRoute(routePlanningOptions, routePlanningCallback)

Retrieve the calculated route using the RoutePlanningCallback you passed when planning the route.

1private val routePlanningCallback = object : RoutePlanningCallback {
  override fun onSuccess(result: RoutePlanningResponse) {
      route = result.routes.first()
      // Place the code here to start navigation, as described in the following instructions.
  }
  override fun onFailure(failure: RoutingFailure) {
      Log.e("StartNavigationActivity", "Unable to calculate a route: " + failure.message)
  }
  override fun onRoutePlanned(route: Route) = Unit
10}

Once you have retrieved the route, create and enable the LocationProvider. Refer to the Built-in location providers and the Location module guides for more information.

1val routeGeoLocations = route.geometry.map { GeoLocation(it) }
2val simulationStrategy = InterpolationStrategy(routeGeoLocations)
3val locationProvider = SimulationLocationProvider.create(strategy = simulationStrategy)
4locationProvider.enable()

Now you can configure the navigation using:

A context for initializing Android dependencies
Your TomTom API key
The previously created location provider
a RoutePlanner to be used for routing requests during replanning
default values for the remaining Configuration parameters.

1val navigationTileStore = NavigationTileStore.create(
2    this,
3    NavigationTileStoreConfiguration(
4        apiKey = TOMTOM_API_KEY,
5        baseUri = URI(NAVIGATION_TILES_API)
6    )
7)
8val routeReplanner = OnlineRouteReplannerFactory.create(routePlanner)
9val navigationConfiguration = Configuration(
10    context = this,
11    locationProvider = locationProvider,
12    navigationTileStore = navigationTileStore,
13    routeReplanner = routeReplanner
14)

Next, create the TomTomNavigation object and register a ProgressUpdatedListener to listen to route progress updates:

val tomTomNavigation = OnlineTomTomNavigationFactory.create(navigationConfiguration)
tomTomNavigation.addProgressUpdatedListener(progressUpdatedListener)

Once you have created and initialized the TomTomNavigation object and added the navigation event listener, you can start navigation along the route.

To start navigation along a route, you first need to specify NavigationOptions that include the active RoutePlan. The RoutePlan consists of a Route and the RoutePlanningOptions used for planning it.

1val routePlan = RoutePlan(route, routePlanningOptions)
2val navigationOptions = NavigationOptions(routePlan)
3tomTomNavigation.start(navigationOptions)

Once you have started the navigation session, TomTomNavigation will:

Request locations from the LocationProvider.
Process the incoming locations and issue various events with specific data, such as map-matched locations.
Send out guidance events.

Retrieving route progress information

With navigation started, you can listen to route progress updates and retrieve the travelled distance and the remaining travel time.

1private val progressUpdatedListener = ProgressUpdatedListener { routeProgress ->
2    Log.v("StartNavigationActivity", "travelled distance: " + routeProgress.distanceAlongRoute)
3    Log.v("StartNavigationActivity", "remaining travel time: " + routeProgress.remainingTime)
4}

In addition to route progress updates, you can also listen to and handle events for route updates, deviations, lane guidance, waypoint arrival, and reaching a destination. Refer to the Turn-by-turn navigation to find out more about supported navigation events.

Next steps

Now that you know how to start navigation with a route and have learnt about navigation events, here are the recommendations on what to explore next: