Traffic

This guide explains how to integrate live map-matched traffic information into the SDK that can be used for navigation, route calculation and visualization. Map-matched traffic events are those that include references to the provided maps. The traffic module downloads map-agnostic events from the server and matches them to the provided maps. The traffic module provides events for use cases such as guidance, route calculation, horizon and map visualization, in the form of traffic incidents. It provides traffic details according to the Traffic interface, including event duration, cause, and type. Traffic data can be retrieved near the current location, and optionally along the route.

The Traffic Module provides the capability to operate in two distinct modes:

1. TPEG Traffic on online and offline map data This option allows the use of a Traffic Client in hybrid mode, with two different map sources: online and offline. With this approach, TPEG traffic events can be decoded on either one or both maps simultaneously.
2. Legacy TPEG Traffic on an offline map In this option, TPEG Traffic events are obtained from the server and decoded locally on the offline map.

NOTE: This option is legacy and new features won’t be available. It is preferable to use the first option, where the TPEG Traffic can be map-matched to any map source.

By offering these two options, the Traffic Module caters to diverse requirements and provides flexibility in handling TPEG traffic data.

Setup

Configure the project as described in the Project setup guide .

Add the following dependencies to the build.gradle.kts file of your application module and synchronize the project.

1
implementation("com.tomtom.sdk.traffic:client:1.26.4")
2
implementation("com.tomtom.sdk.traffic:traffic:1.26.4")

Integrating and configuring traffic

After setting up the project, initialize the Traffic object, which serves as the entry point for accessing traffic data, using the TrafficClientFactory class. Based on the current location, a first snapshot is created containing all traffic events within a specified vicinity determined by the given radius. Additionally, traffic along planned routes can be downloaded. See section Integrating traffic for route calculation within vicinity . The snapshots are updated every minute, and the snapshot frequency can be adjusted using the TrafficTpegConfiguration class. For further configuration of the Traffic client, you can explore the API documentation .

Instantiating the Traffic Client

The Traffic Client can be initialized in various ways, depending on your needs and requirements. In this example, the Traffic object is created using the TrafficDataProviderFactory. The traffic module can be initialized in three different modes: online, offline, and hybrid. The initialization process varies depending on the mode selected. Each mode requires passing a different data store to map-match traffic events.

Traffic in offline mode

1
val yourApiKey = "YOUR API KEY"
2
val mapPath = Path("/path/to/map")
3
val keyStorePath = Path("/path/to/keyStore")
4
val localNdsStore =
5
    NdsStore.create(applicationContext, NdsStoreConfiguration(mapPath.toFile(), keyStorePath.toFile()))
6
traffic =
7
    TrafficClientFactory.createOfflineMode(
8
        applicationContext,
9
        yourApiKey,
10
        localNdsStore.value(),
11
        locationProvider,
12
        Locale.getDefault(),
13
    )

Traffic in online mode

1
val yourApiKey = "YOUR API KEY"
2
val localTileStore =
3
    NavigationTileStore.create(applicationContext, NavigationTileStoreConfiguration(yourApiKey))
4
traffic =
5
    TrafficClientFactory.createOnlineMode(
6
        applicationContext,
7
        yourApiKey,
8
        localTileStore,
9
        locationProvider,
10
        Locale.getDefault(),
11
    )

Hybrid Traffic

1
val yourApiKey = "YOUR API KEY"
2
val mapPath = Path("/path/to/map")
3
val keyStorePath = Path("/path/to/keyStore")
4
val localTileStore =
5
    NavigationTileStore.create(applicationContext, NavigationTileStoreConfiguration(yourApiKey))
6
val localNdsStore =
7
    NdsStore.create(applicationContext, NdsStoreConfiguration(mapPath.toFile(), keyStorePath.toFile()))
8
hybridStore = HybridNavigationDataStore.create(
9
    ndsMapContext = NdsMapContext(localNdsStore.value(), null),
10
    tileStore = localTileStore,
11
)
12
traffic =
13
    TrafficClientFactory.createHybridMode(
14
        applicationContext,
15
        yourApiKey,
16
        hybridStore,
17
        locationProvider,
18
        Locale.getDefault(),
19
    )

Legacy Traffic in offline mode

1
val yourApiKey = "YOUR API KEY"
2
val mapPath = Path("/path/to/map/")
3
val keyStorePath = Path("/path/to/keyStore")
4
val localNdsStore =
5
    NdsStore.create(applicationContext, NdsStoreConfiguration(mapPath.toFile(), keyStorePath.toFile()))
6
traffic =
7
    TrafficClientFactory.create(
8
        applicationContext,
9
        yourApiKey,
10
        localNdsStore.value(),
11
        locationProvider,
12
        Locale.getDefault(),
13
    )

This is a legacy method for creating the Traffic Client. It only exists for backwards compatibility reasons and should not be used any more and is going to be removed in the future.

Using the Traffic module

Once the Traffic Client is created, it can be used with other parts of the SDK, such as map visualization or route calculation.

Displaying traffic on the map

For offline use cases, you can display traffic incidents on the map as provided by the traffic provider, e.g., in the vicinity of the current location. Traffic information for arbitrary locations and traffic flow are not supported. To display traffic the on map, the traffic data provider must be added when setting the map data provider. The following code snippet demonstrates how to show traffic on the map, while setting the map data provider.

1
TomTomMapConfig.customDataProvidersFactoryFunction = {
2
    listOf(
3
        TileOfflineDataProviderFactory.createOfflineDataProvider(ndsStore),
4
        TrafficDataProviderFactory.createTrafficDataProvider(traffic),
5
    )
6
}

Integrating traffic for route calculation within vicinity

When instantiating the OfflineRoutePlanner, add the reference to the traffic object so the routing client can use traffic information for route planning and route section population. Here is an example of how this can be achieved:

1
routePlanner = OfflineRoutePlanner.create(ndsStore, traffic)

Integrating traffic for route calculation beyond the immediate vicinity

The TomTom Traffic service supports traffic along planned routes, providing additional traffic information for offline routes. However, enabling traffic information for offline routes may lead to increased data consumption. To receive traffic information along planned routes, you can enable this feature by using the RouteAddedListener and the RouteRemovedListener from the Navigation module as shown in the following example:

1
@Suppress("unused")
2
private val routeAddedListener by lazy {
3
    RouteAddedListener { _, _, _ ->
4
        tomTomNavigation.navigationSnapshot?.routes?.let { traffic.updateRoutesForTraffic(it.map { it.geometry }) }
5
    }
6
}
7

8
@Suppress("unused")
9
private val routeRemovedListener by lazy {
10
    RouteRemovedListener { route, _ ->
11
        tomTomMap.routes.find { it.tag == route.id.toString() }?.remove()
12
        tomTomNavigation.navigationSnapshot?.routes?.let { traffic.updateRoutesForTraffic(it.map { it.geometry }) }
13
    }
14
}
15

16
@Suppress("unused")
17
private fun initTpegTrafficWithTrafficAlongRoutes() {
18
    tomTomNavigation =
19
        OfflineTomTomNavigationFactory.create(
20
            Configuration(
21
                context = this,
22
                ndsStore = ndsStore,
23
                locationProvider = locationProvider,
24
                routePlanner = routePlanner,
25
            ),
26
        )
27
}

Integrating traffic with horizon view

Coming soon…​

Next steps

Since you have learned how to support traffic on offline maps, here are recommendations for the next steps:

• Search : Learn how to convert geographic coordinates into a human-readable address.

By diving deeper into these areas, you can unlock the full potential of offline maps in your application.