Skip to main content

Electronic horizon

Mapbox Electronic Horizon is a feature of the Mapbox Navigation SDK that surfaces map data along the probable path (or paths) of a vehicle within the road network to anticipate conditions beyond the physical "visible" horizon. The data provided by the electronic horizon enables capabilities like adaptive cruise control, proactive driver alerts for upcoming congestion, speed change and dangerous curves, and available alternative paths. Mapbox Electronic Horizon is designed for Advanced Driver Assistance Systems (ADAS) for in-vehicle deployment, but it can also be used in mobile iOS applications.

Mapbox Electronic Horizon is in public beta

The Mapbox Electronic Horizon feature of the Mapbox Navigation SDK is in public beta and is subject to changes, including its pricing. Use of the feature is subject to the beta product restrictions in the Mapbox Terms of Service. Mapbox reserves the right to end any free tier or free evaluation offers at any time and require customers to place an order to purchase the Mapbox Electronic Horizon feature, regardless of the level of use of the feature.

Turn-by-turn and free-drive navigation

The Mapbox Navigation SDK allows users to navigate in two different modes: turn-by-turn and free-drive navigation. The electronic horizon feature works in both modes.

  • During turn-by-turn navigation (also called active navigation), the user-selected route and its metadata are used as the path for the electronic horizon.

  • During free-drive navigation (also called passive navigation), the electronic horizon will determine the most probable path from the vehicle's current location.

For both turn-by-turn and free-drive navigation, the electronic horizon and its metadata are exposed via the same interface in the Navigation SDK as described below.

Configuring electronic horizon detection

Initialize an ElectronicHorizonOptions object to configure electronic horizon detection. And provide it to RouteController.startUpdatingElectronicHorizon(with:) or PassiveLocationManager.startUpdatingElectronicHorizon(with:) as the parameter to start electronic horizon updates. To begin receiving electronic horizon updates, set up observers of electronic horizon–related notifications.

ElectronicHorizonOptions reference

Define the options for the ElectronicHorizon.


Electronic horizon notifications are only fired when the trip session is started and external resources, navigation tiles, are downloaded, so notifications might not fire right away.

Most probable path

Mapbox Electronic Horizon represents the road network ahead of the user as a tree of edges. For example, an edge may represent a road segment between two intersections or between the two ends of a bridge. An edge may traverse multiple road objects, and a road object may be associated with multiple edges. Each intersection has outlet edges, each of which represents a connecting road segment with a calculated probability that the user will transition to it.

Based on the device's location and user-selected route (if applicable), Mapbox Electronic Horizon determines the most likely path a user may take and provides a most probable path (MPP). The MPP contains data in a tree-like structure where edges have a level attribute equal to 0 and side-branches have a level attribute equal to 1 or higher based on their position relative to the current edge.

In most cases the electronic horizon will return one MPP, but if there are two or more alternatives at an intersection that have a similar probability (a difference less or equal to 5%) the electronic horizon might return several MPP paths. You can choose the MPP with a slightly higher probability or, if you have additional information about the road conditions, you can suggest which MPP the user should choose.

Observing position notifications

To find out when the electronic horizon or MPP changes due to a user location update, observe electronicHorizonDidUpdatePosition notifications.

func startUpdatingPosition() {
selector: #selector(didUpdateElectronicHorizonPosition),
name: .electronicHorizonDidUpdatePosition,
object: nil)

The Notification.userInfo dictionary contains the electronic horizon edge structure in treeKey and the user’s position in the routing graph in positionKey.

@objc func didUpdateElectronicHorizonPosition(_ notification: Notification) {
let position = notification.userInfo?[RoadGraph.NotificationUserInfoKey.positionKey] as? RoadGraph.Position,
let horizon = notification.userInfo?[RoadGraph.NotificationUserInfoKey.treeKey] as? RoadGraph.Edge
else { return }

treeKey is set to an Edge object, which is a starting point in a tree of edges that you can traverse recursively to explore the routing graph in the vicinity of the user.

You can also unsubscribe from electronic horizon position notifications during the lifetime of an object.

func stopUpdatingPosition() {
NotificationCenter.default.removeObserver(self, name: .electronicHorizonDidUpdatePosition, object: nil)

Get more details about an edge

To get more details about an edge, such as its name and shape, get the active RoadGraph object from the RouteController.roadGraph or PassiveLocationManager.roadGraph, then pass the edge’s identifier into the RoadGraph object’s methods.

Road objects

Road objects represent routing-related landmarks within the routing graph, such as traffic incidents, tunnel entrances, and border crossings.

Observing road object notifications

To find out when the user enters or exits the geofence associated with a road object, observe the electronicHorizonDidEnterRoadObject and electronicHorizonDidExitRoadObject notifications, respectively.

func startUpdatingRoadObjects() {
selector: #selector(didEnterOrExitRoadObject),
name: .electronicHorizonDidEnterRoadObject,
object: nil)
selector: #selector(didEnterOrExitRoadObject),
name: .electronicHorizonDidExitRoadObject,
object: nil)

The Notification.userInfo dictionary contains the road object identifier in roadObjectIdentifierKey. didTransitionAtEndpointKey indicates whether the user transitioned to or from the road object at one of its endpoints or whether they did so somewhere along the road object.

@objc func didEnterOrExitRoadObject(_ notification: Notification) {
let identifier = notification.userInfo?[RoadGraph.NotificationUserInfoKey.roadObjectIdentifierKey] as? RoadObjectIdentifier,
let didTransitionAtEndpoint = (notification.userInfo?[RoadGraph.NotificationUserInfoKey.didTransitionAtEndpointKey] as? NSNumber)?.boolValue
else { return }

You can also unsubscribe from road object notifications during the lifetime of an object.

func stopUpdatingRoadObjects() {
NotificationCenter.default.removeObserver(self, name: .electronicHorizonDidEnterRoadObject, object: nil)
NotificationCenter.default.removeObserver(self, name: .electronicHorizonDidExitRoadObject, object: nil)

Get more details about a road object

To get more details about a road object, such as its location and type, get the active RoadObjectsStore object from the RouteController.roadObjectsStore or PassiveLocationManager.roadObjectStore, then pass the road object identifier into the RoadObjectsStore object’s methods.

Was this page helpful?