Developer

Quickstart

VERSION 2.1.2

This guide shows you how to start turn-by-turn navigation using the TomTom Maps and 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 = "2.1.2"
2implementation("com.tomtom.sdk:init:$version")
3implementation("com.tomtom.sdk.location:provider-simulation:$version")
4implementation("com.tomtom.sdk.routing:route-planner:$version")

Starting navigation

Before starting navigation with a route, you need to initialize the TomTomSdk object, plan a route, and enable a LocationProvider.

First, initialize the navigation object using:

  • Android context.
  • Your TomTom API key.
1TomTomSdk.initialize(
2    context = application,
3    sdkConfiguration = buildSdkConfiguration(
4        context = application,
5        apiKey = TOMTOM_API_KEY,
6    ),
7)
8val tomTomNavigation = TomTomSdk.navigation

After initializing TomTomSdk, 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 = TomTomSdk.createRoutePlanner()
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 = buildRoutePlanningOptions(itinerary = itinerary)
7    routePlanner.planRoute(
8        routePlanningOptions,
9        object : RoutePlanningCallback {
10            override fun onSuccess(result: RoutePlanningResponse) {
11                route = result.routes.first()
12                startNavigation()
13            }
14

15            override fun onFailure(failure: RoutingFailure) {
16                Log.e(TAG, "Unable to calculate a route: " + failure.message)
17            }
18        },
19    )
20}

After planning the route, enable the LocationProvider. Default LocationProvider is provided by TomTomSdk. Refer to the Location module guides for more information.

TomTomSdk.locationProvider.enable()

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    TomTomSdk.initialize(
3        context = application,
4        sdkConfiguration = buildSdkConfiguration(
5            context = application,
6            apiKey = TOMTOM_API_KEY,
7        ),
8    )
9    val tomTomNavigation = TomTomSdk.navigation
10

11    TomTomSdk.locationProvider.enable()
12

13    tomTomNavigation.addProgressUpdatedListener(progressUpdatedListener)
14

15    val routePlan = RoutePlan(route, routePlanningOptions)
16    val navigationOptions = NavigationOptions(routePlan)
17    tomTomNavigation.start(navigationOptions)
18}

Once you have started navigation, TomTomNavigation will:

  • Track locations using the LocationProvider.
  • Process incoming locations and publish navigation events such as map-matched positions or route guidance data. To access this information, add the appropriate observers to the TomTomNavigation object. To learn more about how map-matched positions are generated based on the location updates provided by the system, see the Map matching page.

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: