Developer

Horizon hazards

VERSION 1.20.0
PUBLIC PREVIEW

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

The Hazards Warning service helps anticipate the road ahead. The warnings published are safety-related, meant to inform or warn the driver of an upcoming (dangerous) situation, such as slippery roads, animals or objects in the road, fog-induced reduced visibility and many other hazards.

The Hazards SDK provides data for various categories of hazards, including:

Configuring the horizon engine

Having completed the Retrieving horizon data guide, you are now able to set up the horizon engine and start navigation to retrieve horizon data.

Specifying horizon options

To subscribe to hazard horizon elements, specify HazardElementTypeUrl in the list of element types of interest.

1private val horizonOptionsHazards =
2    HorizonOptions(
3        elementTypes = listOf(HazardElementType),
4        mainPathSearchOptions =
5            MainPathSearchOptions(
6                searchDistancePolicy = RouteLengthPolicy,
7            ),
8    )

Configuring navigation

The Hazards feature requires configuring the hazards data source before starting navigation. You need to create a HazardConfiguration object and inject it into the navigation Configuration constructor. When you set up the HazardConfiguration object, specify the API key that grants your application access to the TomTom Hazards service.

In addition to configuring the hazards data source, you must also increase the navigation tile prefetching radius to 15 km. This ensures that enough map data is prefetched to allow the exposure of hazard data at the current vehicle position. With a smaller prefetching radius there is no guarantee that the hazard data is exposed in the horizon.

1val navigationTileStore =
2    NavigationTileStore.create(
3        context = this,
4        navigationTileStoreConfig = NavigationTileStoreConfiguration(
5            apiKey = TOMTOM_API_KEY,
6            prefetchingConfiguration = PrefetchingConfiguration(prefetchedAreaRadius = PREFETCHED_AREA_RADIUS),
7        ),
8    )
9val navigationConfiguration =
10    Configuration(
11        context = this,
12        locationProvider = locationProvider,
13        navigationTileStore = navigationTileStore,
14        routePlanner = routePlanner,
15        hazardsConfiguration = HazardsConfiguration(TOMTOM_API_KEY),
16    )

Registering a horizon updated listener

Before starting navigation, register a HorizonUpdatedListener to listen for horizon updates with the horizon options you have defined.

val tomTomNavigation = OnlineTomTomNavigationFactory.create(navigationConfiguration)
tomTomNavigation.addHorizonUpdatedListener(horizonOptionsHazards, horizonUpdatedListener)

Starting navigation

Then, start navigation with a route as described in the Retrieving horizon data guide.

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

Retrieving hazards

With navigation started, you will now listen to horizon updates and retrieve hazard data.

If a hazard zone stretches beyond the end of the horizon, the SDK only provides data for the part of the zone within the horizon length. As the horizon is extended ahead of the vehicle while the vehicle moves along the zone hazard location, the end offset of the hazard horizon element is updated accordingly.

Filtering hazards

Some of the retrieved hazards may not be relevant to the driver. For example, the driver may not be interested in strong winds as it is not a concern for the vehicle location. To filter out irrelevant hazards, you can simply add additional filtering during the retrieval of the hazard horizon elements:

1private fun HorizonPath.retrieveHazardElements(): List<HazardElement> = getElements(HazardElementType)
2    .map { it as HazardElement }
3    .filter { element ->
4        // Filters out hazards of type StrongWind
5        element.hazard.type != HazardType.StrongWind
6    }

Next steps

Now that you know how to retrieve horizon hazards data, here are the recommendations on what to explore next: