Slow traffic notification

Experimental API

The Driver Notifications API is in a preview state and has a high chance of being changed in the future.

The SlowTrafficNotificationProvider monitors traffic conditions along the current route and generates notifications. It evaluates traffic data using congestion levels, distances, and predicted durations, to identify slow traffic segments and notify drivers when delays exceed a configurable threshold. It continuously tracks route progress and evaluates traffic conditions in real-time. The provider allows customization of thresholds for congestion levels, delay tolerances, and check intervals using SlowTrafficNotificationOptions. When the app receives a notification, it can additionally analyze alternatives to find a faster route or notify the user with a UI popup.

1. Review the Directions API annotations

The SlowTrafficNotificationProvider relies on specific traffic-related annotations from the navigation backend to check and detect slow traffic conditions. The token from the Mapbox account used for accessing these API must have the necessary permissions to retrieve distances for route segments, predicted durations for the route segments, and congestion levels. Below are the detailed descriptions of the required Directions API annotations:

Distance (LegAnnotation.distance):

• Represents the distance of each geometry segment in meters.
• Used to calculate the total affected distance of slow traffic segments.

Duration (LegAnnotation.duration)

• Represents the time required to travel each geometry segment in seconds.
• Used to calculate the total affected time of slow traffic segments.

Free-flow speed (LegAnnotation.freeflowSpeed):

• Represents the typical speed under free-flow conditions (e.g., during low traffic times) for each geometry segment in kilometers per hour.
• Used to estimate the free-flow duration for comparison with actual travel times.

Congestion Numeric (LegAnnotation.congestionNumeric):

• Represents the congestion level for each geometry segment as a numeric value.
• Used to identify slow traffic conditions by comparing the congestion level against a configurable range.

2. Use configuration options

Use SlowTrafficNotificationOptions to configure SlowTrafficNotificationProvider. Whenever the Navigation SDK detects a segment of a route where the duration is increased by at least trafficDelay (compared to its usual duration) due to traffic with a congestion level within slowTrafficCongestionRange, this segment will be reported to the user via a SlowTrafficNotification object.

Option	Default	Description
trafficDelay	2 min	Minimum delay caused by heavy traffic ahead to trigger a notification.
slowTrafficPeriodCheck	10 sec	Interval at which slow traffic conditions are checked.
slowTrafficCongestionRange	[60;100]	The range of numeric congestion levels considered as slow traffic.

val options = SlowTrafficNotificationOptions.Builder()
    .slowTrafficCongestionRange(50..90)
    .slowTrafficPeriodCheck(15.seconds)
    .trafficDelay(3.minutes)
    .build()

If runtime update of the provider configuration is needed, apply new SlowTrafficNotificationOptions to already created SlowTrafficNotificationProvider instance.

val builder = SlowTrafficNotificationOptions.Builder()
slowTrafficNotificationProvider.options = builder
    .trafficDelay(config.slowTrafficConfig.minSlowTrafficDelay)
    .slowTrafficCongestionRange(trafficType.slowTraffic)
    .build()

3. Setup SlowTrafficNotificationProvider

GUIDE

Get started with Driver Notifications

Learn how to setup Driver Notifications.

4. Receive slow traffic notification

The SlowTrafficNotification class represents a notification generated when next occurrence of the slow traffic is detected. It provides detailed information about the affected part of the route, including the geometry range, delay, and distance.

Data Field	Description
legIndex	The index of the route leg where slow traffic is detected.
slowTrafficGeometryRange	The range of geometry indices affected by slow traffic.
freeFlowRangeDuration	The duration it would take to traverse the affected range under free-flow conditions.
slowTrafficRangeDuration	The duration it takes to traverse the affected range under current slow traffic conditions.
slowTrafficRangeDistance	The distance of the affected range in meters.
slowTrafficDelay	The delay caused by slow traffic, calculated as the difference between slow and free-flow durations.

Was this page helpful?