Starting navigation

VERSION 1.1.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 traveled distance.

Project setup

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

1val version = "1.1.0"
2implementation("com.tomtom.sdk.location:provider-simulation:$version")
3implementation("com.tomtom.sdk.navigation:navigation-online:$version")
4implementation("com.tomtom.sdk.routing:route-planner-online:$version")

Before starting navigation with a route, you need to plan the route and set up navigation dependencies:

NavigationTileStore, which provides online navigation tile data.
LocationProvider, which provides 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.

1fun planRoute() {
  routePlanner = OnlineRoutePlanner.create(context = this, apiKey = TOMTOM_API_KEY)
  val amsterdam = GeoPoint(latitude = 52.37616, longitude = 4.90828)
  val rotterdam = GeoPoint(latitude = 51.90546, longitude = 4.46662)
  val itinerary = Itinerary(origin = amsterdam, destination = rotterdam)
  routePlanningOptions = RoutePlanningOptions(
      itinerary = itinerary,
      guidanceOptions = GuidanceOptions(),
      vehicle = Vehicle.Car()
  )
  routePlanner.planRoute(
      routePlanningOptions,
      object : RoutePlanningCallback {
          override fun onSuccess(result: RoutePlanningResponse) {
              route = result.routes.first()
              startNavigation()
          }
18
          override fun onFailure(failure: RoutingFailure) {
              Log.e(TAG, "Unable to calculate a route: " + failure.message)
          }
22
          override fun onRoutePlanned(route: Route) = Unit
      }
  )
26}

After planning the route, create the NavigationTileStore as follows:

1private fun createNavigationTileStore(): NavigationTileStore {
  val configuration = NavigationTileStoreConfiguration(
      apiKey = TOMTOM_API_KEY
  )
  return NavigationTileStore.create(
      context = this,
      navigationTileStoreConfig = configuration
  )
9}

Then, create and enable the LocationProvider. Refer to the Built-in location providers and the Location module guides for more information.

SimulationLocationProvider is an implementation of the LocationProvider interface that can be used for navigation configuration. The following snippet shows how to create and enable a SimulationLocationProvider. For a list of all the available location providers, refer to the Built-in location providers guide.

1private fun createSimulationLocationProvider(): LocationProvider {
  val routeGeoLocations = route.geometry.map { GeoLocation(it) }
  val simulationStrategy = InterpolationStrategy(routeGeoLocations)
  return SimulationLocationProvider.create(strategy = simulationStrategy).also { simulationLocationProvider ->
      simulationLocationProvider.enable()
  }
7}

Now you can configure the navigation using:

Android context.
The previously created NavigationTileStore.
The previously created LocationProvider.
The previously created RoutePlanner, that is used for routing requests during replanning.

1private fun createNavigationConfiguration(): Configuration {
  val navigationTileStore = createNavigationTileStore()
  val simulationLocationProvider = createSimulationLocationProvider()
  return Configuration(
      context = this,
      navigationTileStore = navigationTileStore,
      locationProvider = simulationLocationProvider,
      routePlanner = routePlanner
  )
10}

Next, create the TomTomNavigation object with the previous configuration.

val configuration = createNavigationConfiguration()
val tomTomNavigation = OnlineTomTomNavigationFactory.create(configuration)

To receive route progress updates during navigation, implement a ProgressUpdatedListener and add it to the initialized TomTomNavigation object.

tomTomNavigation.addProgressUpdatedListener(progressUpdatedListener)

To start navigation along a route, pass the NavigationOptions object which sets the active route to the above-created route.

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

Combine all the previous snippets into the following function:

1fun startNavigation() {
2    val configuration = createNavigationConfiguration()
3    val tomTomNavigation = OnlineTomTomNavigationFactory.create(configuration)
4
5    tomTomNavigation.addProgressUpdatedListener(progressUpdatedListener)
6
7    val routePlan = RoutePlan(route, routePlanningOptions)
8    val navigationOptions = NavigationOptions(routePlan)
9    tomTomNavigation.start(navigationOptions)
10}

Once you have started navigation, TomTomNavigation will:

Track locations using the LocationProvider.
Process the incoming locations and publish navigation events with data, such as map-matched locations or route guidance. To retrieve this data, you must add the appropriate observers to TomTomNavigation.

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(TAG, "Distance along the route: ${routeProgress.distanceAlongRoute}")
3    Log.v(TAG, "Remaining travel time: ${routeProgress.remainingTime}")
4}

In addition to route progress updates, you can also listen to and handle events for route updates, deviations, route and 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: