Horizon hazards

VERSION 2.1.2

The Hazards Warning service helps drivers anticipate potential dangers on the road. It provides safety-related warnings about upcoming hazardous situations, such as slippery surfaces, animals or objects in the roadway, reduced visibility due to fog, and other hazards.

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

Configuring horizon

After completing the Retrieving horizon data guide, you can subscribe for horizon updates and start navigation to retrieve horizon data.

Specifying horizon options

To subscribe to hazard horizon elements, create HorizonOptions via the createHorizonOptions method and specify HazardElementType in the list of element types of interest. The horizon path parameters defined within createHorizonOptions are appropriate for most use cases and can be utilized in both free driving and active guidance scenarios.

1
val horizonOptions = buildHorizonOptions(listOf(HazardElementType))

When using the Extended flavor

The Extended flavor of Maps and Navigation SDK for Android is only available upon request. Contact us to get started.

If you prefer to configure the horizon path parameters manually, you can create the HorizonOptions as follows:

1
val horizonOptions =
2
    HorizonOptions(
3
        elementTypes = listOf(HazardElementType),
4
        mainPathSearchOptions =
5
            MainPathSearchOptions(
6
                searchDistancePolicy = ExplicitDistancePolicy(
7
                    searchDistance = PathSearchDistance(maxHorizonLength = Distance.kilometers(2)),
8
                ),
9
            ),
10
        subPathSearchOptions = listOf(
11
            SubPathSearchOptions(
12
                searchDistance = PathSearchDistance(maxHorizonLength = Distance.meters(100)),
13
            ),
14
        ),
15
        numberOfPaths = 10,
16
    )

Registering a horizon updated listener

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

1
tomTomNavigation.addHorizonUpdatedListener(horizonOptions, horizonUpdatedListener)

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

1
val routePlan = RoutePlan(route, routePlanningOptions)
2
val navigationOptions = NavigationOptions(routePlan)
3
tomTomNavigation.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 :

1
private 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:

Retrieving horizon data