SDK for Android Developer's Guide

Traffic-Aware Navigation

With HERE SDK developers can enable turn-by-turn route navigation that takes live traffic information into account. NavigationManager.setTrafficAvoidanceMode() can be used to set the way in which traffic should be handled during navigation.

Three modes are available for traffic avoidance, and they are defined by the following NavigationManager.TrafficAvoidanceMode enumerations. The default mode is DISABLE.

DYNAMIC - Performs traffic-aware rerouting without user input.
In this mode the guidance engine performs periodic route calculations while the device is online. A route calculation is a server request where the server finds the most optimal route by avoiding traffic congestions and calculating speed limits. If the calculated route is different from the current route, the navigation manager automatically switches to the new route. It also triggers NavigationManager.NavigationManagerEventListener.onRouteUpdated(Route) callback method.

Note: You can set the frequency of the route request by using NavigationManager.setRouteRequestInterval().
MANUAL - Provides the traffic-aware rerouting callback NavigationManager.NavigationManagerEventListener.onRouteUpdated(Route).
In this mode no rerouting occurs unless the NavigationManager is explicitly set with the new Route. For more information, see the next section.
DISABLE - Disables traffic-based rerouting.

Manual Traffic-Based Rerouting

If the device is online and NavigationManager.TrafficAvoidanceMode.MANUAL is selected, the guidance engine periodically performs route recalculations while the device is online. You can listen for this recalculation event by implementing onTrafficRerouteBegin(TrafficNotification) method in TrafficRerouteListener.

Route recalculation is a server request where the server finds the most optimal route by avoiding live traffic congestions and calculating road speed limits. If the calculated route is different from the current route, the new route is returned through NavigationManager.TrafficRerouteListener.onTrafficRerouted(Route) callback method. A voice note is also played by the guidance engine. You can then set the new Route to the NavigationManager manually.

TrafficWarner Class

TrafficWarner class is responsible for enabling and handling traffic notifications. Traffic notifications occur if there is a traffic event on the current route and the user's current position is near the event.

To retrieve an instance of the TrafficWarner object, call NavigationManager.getTrafficWarner(). You then can call TrafficWarner.init() to initialize and start the TrafficWarner.

One or more of the following methods can be used to operate traffic warner or to retrieve further information about traffic notifications:

isAhead(TrafficNotification) - determines whether or not a traffic notification is ahead of the last callback position
isOnRoute(Route, TrafficNotification) - determines if a traffic notification is on a given route
isValid() - determines if the traffic warner is valid
stop() - stops the traffic warner
start() - starts the traffic warner

Note: The navigation manager must be in the Running state for the traffic warner to work correctly.

To listen for traffic notifications, a listener must be added via TrafficWarner.addListener().

TrafficNotification and TrafficNotificationInfo Classes

TrafficWarner.Listener provides a callback that returns a TrafficNotification object that is relevant to the current navigation session. This TrafficNotification contains a list of TrafficNotificationInfo instances associated with the traffic notification retrievable through TrafficNotification.getInfoList().

TrafficNotificationInfo class encapsulates the details of a traffic notification. TrafficNotificationInfo.Type defines the type of traffic notification with regards to the current route.

The following methods can be used to retrieve details about a TrafficNotificationInfo instance:

getType() - gets the type of traffic notification info
getDistanceInMeters() - gets the distance from the last callback position to the traffic notification

Finding Alternative Routes with Traffic Avoidance Mode Enabled

It is called when the navigation manager has found alternative routes for current one during navigation. The following is an example of an AlternativeRoutesListener.onAlternativeRoutesUpdated().

public void onAlternativeRoutesUpdated(final List<Route> alternativeRoutes) {
  // remove old alternative routes from the map
  map.removeMapObjects(currentAlternativeRoutes);

  // enumerate all available alternative routes
  for (Route route : alternativeRoutes) {
    // create new map route object
    MapRoute mapRoute = new MapRoute(route);
    // set random color for the map route
    mapRoute.setColor(Color.argb(255, rnd.nextInt(256), rnd.nextInt(256), rnd.nextInt(256));
    // update internal storage
    currentAlternativeRoutes.add(mapRoute);
    // add alternative route to the map
    map.addMapObject(mapRoute);
  }
}