Route alerts
Route alerts are notifications about upcoming events or points of interest along the selected route. Unlike banner and voice instructions, which are necessary to guide the user along the route, route alerts are strictly informational. If you choose to use route alerts as part of a guided navigation session, you are in control of when and how to display or announce these alerts to the user.
Two common ways to use route alerts are:
- In a route overview to display the location of alerts along the route
- In an active guidance to display an alert during a navigation session
Each route alert contains information about the type of alert and optional metadata about the alert.
Get notified about route alerts
There are two ways to get a list of route alerts along the route.
Observe RouteAlerts
The Navigation SDK's RouteAlertsObserver interface notifies you when the Navigation SDK detects that the route has changed or been cleared and provides the list of alerts on the new route, if there are any. The alerts are in an ascending order based on the occurrence time along the route.
Create the RouteAlertsObserver interface object:
val routeAlertsObserver = object : RouteAlertsObserver {
override fun onNewRouteAlerts(routeAlerts: List<RouteAlert>) {
}
}
RouteAlertsObserver will emit an empty list when in free-drive mode.Register the RouteAlertsObserver object with your already-instantiated MapboxNavigation object.
override fun onStart() {
super.onStart()
mapView.onStart()
mapboxNavigation.registerRouteAlertsObserver(routeAlertsObserver)
}
Don't forget to unregister the RouteAlertsObserver interface:
override fun onStop() {
super.onStop()
mapView.onStop()
mapboxNavigation.unregisterOffRouteObserver(offRouteObserver)
}
Listen to RouteProgress
The upcoming RouteAlerts will emit as RouteProgress.upcomingRouteAlerts from the RouteProgressObserver, based on the progress along the route. Upcoming RouteAlerts will also include the UpcomingRouteAlert.distanceToStart as this value changes during navigation.
RouteAlert
RouteAlert is an abstract class that serves as a base for all route alerts. It contains information about the alert's type, position, distance from the beginning of the route, and, optionally, geometry details.
Route alert types
Available alert types are:
TunnelEntranceAlertCountryBorderCrossingAlertTollCollectionAlertRestStopAlertRestrictedAreaAlertIncidentAlert
TunnelEntranceAlert
An alert describing a section of the route that continues through a tunnel. The alert begins at the entrance of the tunnel and ends at the exit of the tunnel. For named tunnels, the tunnel name is provided as part of TunnelInfo#name. This may include RouteAlertGeometry as it's a "line" alert.
CountryBorderCrossingAlert
An alert describing a country border crossing along the route. The alert triggers at the point where the administrative boundary changes from one country to another. Two-letter and three-letter ISO 3166-1 country codes are provided for the exiting country and the entering country. See CountryBorderCrossingAdminInfo. This won't include RouteAlertGeometry as it's a "point" alert.
TollCollectionAlert
An alert describing a point along the route where a toll may be collected. Note that this does not describe the entire toll road, rather it describes a booth or electronic gate where a toll is typically charged. See TollCollectionType. This won't include RouteAlertGeometry as it's a "point" alert.
RestStopAlert
An alert about a rest area or service area accessible from the route. The alert marks the point along the route where a driver can choose to pull off to access a rest stop. See RestStopType. This won't include RouteAlertGeometry as it's a "point" alert.
RestrictedAreaAlert
An alert about a segment of a route that includes a restriction. Restricted roads can include private access roads or gated areas that can be accessed but are not open to vehicles passing through. This may include RouteAlertGeometry as it's a "line" alert.
IncidentAlert
An alert providing information about incidents on a route. Incidents can include congestion, mass transit, and more (see IncidentType for the full list of incident types). This may include RouteAlertGeometry if it's a "line" alert.
RouteAlertGeometry
Line-shaped RouteAlerts always include RouteAlertGeometry, which describes the geometry of the alert.
Use LineString.fromPolyline with DirectionsRoute.geometry and the precision argument that was used when requesting the route (RouteOptions.Builder.geometries) to decode the route. When decoded, you can find the geometry of the alert using the startGeometryIndex and endGeometryIndex values as arguments for LineString.coordinates. This list of coordinates can be used to create and draw the geometry with LineString.fromLngLats. Also see RouteAlertGeometry.toLineString extension which automates above.
val directionsRoute = ...
val tunnelSource = ...
val tunnelAlert = ...
// get your routes full geometry
val routeLineString = LineString.fromPolyline(directionsRoute.geometry(), Constants.PRECISION_6)
// find the sub-line of the route that represents the alert's geometry
val tunnelLineString = tunnelAlert.alertGeometry.toLineString(routeLineString)
// update your GeoJsonSource to display it on the map
val tunnelFeature = Feature.fromGeometry(tunnelLineString)
tunnelSource.setGeoJson(tunnelFeature)
UpcomingRouteAlert
UpcomingRouteAlerts list is a property of the RouteProgress object that holds the route alerts and the distance from the device's current location to the point where each of alert occurs or starts.
If the alert has a length, and the device has passed the starting point, this value will be negative until the device crosses the finish point of the alert's geometry. This negative value, together with RouteAlertGeometry.length, can be used to calculate the distance since the start of an alert.
See how to integrate and display route alerts.