Retrieving horizon data

Virtual Horizon acts as a digital assistant, extending the driver’s location context beyond their immediate view. It can be used by UI components to improve the driving experience, for example, by informing the driver of what is ahead. This information includes details about upcoming traffic events, vehicle restrictions, and more.

While navigating, you can use Virtual Horizon to retrieve detailed information about the horizon ahead of the vehicle, along the possible trajectories of the vehicle across the road network. Horizon data is delivered to your application as a combination of a HorizonPosition and a HorizonSnapshot .

The SDK provides horizon data for various elements, including:

• StreetElement - Information about a street, such as name.
• SpeedLimitElement - Information about speed limits.
• GeneralRoadPropertiesElement - Information about the road ahead, such as number of lanes, functional road class and driving side.
• CountryInformationElement - Information about the country ahead, including country code, speed limit unit, regional speed limits, etc..
• CityElement - Information about the city ahead, such as its name.
• RailwayCrossingElement - Information about upcoming railway crossings.

This guide focuses on demonstrating how to obtain speed-related data — the current speed limit, the distance to the next speed limit, and the value of the upcoming speed limit — using the public navigation APIs. These insights allow you to create navigation applications that not only guide users accurately but also keep them well-informed.

For more in-depth information, refer to the horizon data types, such as HorizonPosition and HorizonSnapshot .

Configuring horizon

Incorporating horizon data into your navigation application requires the following steps:

• Define your horizon data preferences by specifying HorizonOptions .
• Add a HorizonUpdatedListener to receive data based on your chosen HorizonOptions .
• Start navigation with or without a route as described in the Starting navigation guide .

Specifying horizon options

First, define the set of HorizonOptions . To indicate that you are interested in SpeedLimitElement horizon elements, specify SpeedLimitElementType in the list of element types of interest. The horizon path parameters defined within buildHorizonOptions are appropriate for most use cases and can be utilized in both free driving and active guidance scenarios. The buildHorizonOptions method will create a HorizonOptions instance with a main path search distance that is the minimum between 25 km and the remaining route length when navigating with a route, or 10 km when free driving.

1
private val horizonOptions = buildHorizonOptions(listOf(SpeedLimitElementType))

1
val horizonOptions = HorizonOptions(
2
    elementTypes = listOf(SpeedLimitElementType),
3
    mainPathSearchOptions = MainPathSearchOptions(
4
        searchDistancePolicy = ExplicitDistancePolicy(
5
            searchDistance = PathSearchDistance(
6
                maxHorizonLength = Distance.kilometers(1),
7
            ),
8
        ),
9
    ),
10
)

Starting navigation

To start navigation with a route, follow the Starting navigation guide .

But, instead of adding a listener for route progress updates, make sure you add a HorizonUpdatedListener to listen to horizon updates. You’ll need to use the HorizonOptions returned from the buildHorizonOptions method to subscribe for horizon updates in the listener.

1
fun startNavigation() {
2
    tomTomNavigation.addHorizonUpdatedListener(horizonOptions, horizonUpdatedListener)
3

4
    val routePlan = RoutePlan(route, routePlanningOptions)
5
    val navigationOptions = NavigationOptions(routePlan)
6
    tomTomNavigation.start(navigationOptions)
7
}

Retrieving horizon data

With navigation started, you can listen to horizon updates and retrieve horizon data.

1
private val horizonUpdatedListener =
2
    object : HorizonUpdatedListener {
3
        private var horizonSnapshot: HorizonSnapshot? = null
4

5
        override fun onPositionUpdated(
6
            options: HorizonOptions,
7
            position: HorizonPosition,
8
        ) {
9
            horizonSnapshot?.let { snapshot ->
10
                position.takeIf { it.isOnRoad }?.let { position ->
11
                    snapshot.displayCurrentSpeedLimit(position)
12
                    snapshot.displayNextSpeedLimit(position)
13
                }
14
            }
15
        }
16

17
        override fun onSnapshotUpdated(
18
            options: HorizonOptions,
19
            snapshot: HorizonSnapshot,
20
        ) {
21
            horizonSnapshot = snapshot
22
        }
23

24
        override fun onHorizonReset(options: HorizonOptions) {
25
            // do nothing
26
        }
27
    }

Once you have retrieved the data, you can use it to extract the value of the current speed limit.

1
private fun HorizonSnapshot.displayCurrentSpeedLimit(position: HorizonPosition) {
2
    mainPath()?.getElements(SpeedLimitElementType)
3
        ?.firstOrNull { element -> element.startOffset < position.offset && element.endOffset >= position.offset }
4
        ?.let { element -> (element as SpeedLimitElement).speedLimit }
5
        ?.also { speedLimit ->
6
            when (speedLimit.type) {
7
                SpeedLimit.Type.Limited -> Log.v(TAG, "Speed limit value: " + speedLimit.speed)
8
                SpeedLimit.Type.Unlimited -> Log.v(TAG, "Unlimited speed")
9
            }
10
        }
11
}

You can also extract the distance to the next speed limit and the value of the next speed limit.

1
private fun HorizonSnapshot.displayNextSpeedLimit(position: HorizonPosition) {
2
    mainPath()?.getElements(SpeedLimitElementType)
3
        ?.firstOrNull { element -> element.startOffset >= position.offset }
4
        ?.let { element ->
5
            Log.v(TAG, "Distance to the next speed limit: " + distanceTo(element, position))
6
            (element as SpeedLimitElement).speedLimit
7
        }
8
        ?.also { speedLimit ->
9
            when (speedLimit.type) {
10
                SpeedLimit.Type.Limited -> Log.v(TAG, "Next speed limit value: " + speedLimit.speed)
11
                SpeedLimit.Type.Unlimited -> Log.v(TAG, "Next, unlimited speed")
12
            }
13
        }
14
}

Next steps

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

• Learning more about navigation events