Developer

Starting navigation

VERSION 1.26.4

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

This guide shows you how to start turn-by-turn navigation using the TomTom Navigation SDK for Android, and how to retrieve real-time route progress updates, including traveled distance and remaining travel time.

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.26.4"
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")

Starting navigation

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

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() {
2    routePlanner = OnlineRoutePlanner.create(context = this, apiKey = TOMTOM_API_KEY)
3    val amsterdam = GeoPoint(latitude = 52.37616, longitude = 4.90828)
4    val rotterdam = GeoPoint(latitude = 51.90546, longitude = 4.46662)
5    val itinerary = Itinerary(origin = amsterdam, destination = rotterdam)
6    routePlanningOptions =
7        RoutePlanningOptions(
8            itinerary = itinerary,
9            guidanceOptions = GuidanceOptions(),
10            vehicle = Vehicle.Car(),
11        )
12    routePlanner.planRoute(
13        routePlanningOptions,
14        object : RoutePlanningCallback {
15            override fun onSuccess(result: RoutePlanningResponse) {
16                route = result.routes.first()
17                startNavigation()
18            }
19

20            override fun onFailure(failure: RoutingFailure) {
21                Log.e(TAG, "Unable to calculate a route: " + failure.message)
22            }
23        },
24    )
25}

After planning the route, create the NavigationTileStore as follows:

1private fun createNavigationTileStore(): NavigationTileStore {
2    val configuration =
3        NavigationTileStoreConfiguration(
4            apiKey = TOMTOM_API_KEY,
5        )
6    return NavigationTileStore.create(
7        context = this,
8        navigationTileStoreConfig = configuration,
9    )
10}

Next, 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 complete list of available location providers, see the Built-in location providers guide.

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

Now you can configure navigation using the following components:

1private fun createNavigationConfiguration(): Configuration {
2    val navigationTileStore = createNavigationTileStore()
3    val simulationLocationProvider = createSimulationLocationProvider()
4    return Configuration(
5        context = this,
6        navigationTileStore = navigationTileStore,
7        locationProvider = simulationLocationProvider,
8        routePlanner = routePlanner,
9    )
10}

Next, create the TomTomNavigation object using the configuration created earlier.

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 a NavigationOptions object that sets the active route to the one you created earlier.

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

You can 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:

Retrieving route progress information

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

1private val progressUpdatedListener =
2    ProgressUpdatedListener { routeProgress ->
3        Log.v(TAG, "Distance along the route: ${routeProgress.distanceAlongRoute}")
4        Log.v(TAG, "Remaining travel time: ${routeProgress.remainingTime}")
5    }

In addition to route progress updates, you can also listen for and handle events such as route updates, deviations, route and lane guidance, waypoint arrivals and reaching the destination. Refer to the Turn-by-turn navigation guide to learn more about supported navigation events.

Next steps

Now that you know how to start navigation and handle navigation events, here are some recommended next steps: