SDK for iOS Developer's Guide

Traffic-Aware Navigation

With the HERE SDK, developers can enable turn-by-turn route navigation that takes live traffic information into account. The setTrafficAvoidanceMode: method in NMANavigationManager 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 NMATrafficAvoidanceMode enumerations. The default mode is DISABLE.
  • NMATrafficAvoidanceDynamic - 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 the navigationManager:didUpdateRoute: delegate method.

    Note: You can set the frequency of the route request by using setRouteRequestInterval:.
  • NMATrafficAvoidanceManual - Provides the traffic-aware rerouting callback navigationManager:didUpdateRoute:.

    In this mode, no rerouting occurs unless the NMANavigationManager is explicitly set with the new NMARoute. For more information, see the next section.

  • NMATrafficAvoidanceDisabled - Disables use of traffic for rerouting purpose.

Manual Traffic-Based Rerouting

If the device is online and the NMATrafficAvoidanceManual mode is selected, the guidance engine periodically performs route recalculations while the device is online. You can listen to this recalculation event by implementing the navigationManger:didChangeRoutingState: method in NMANavigationManagerDelegate and checking for the state change from NMATrafficEnabledRoutingStateOn or NMATrafficEnabledRoutingStateNotAvilable to NMATrafficEnabledRoutingStateOngoingRequest.

Note: The navigationManger:didChangeRoutingState: callback is also called in automatic avoidance mode.

Route recalculation is a server request. The calculation finds the most optimal route by avoiding congestions and calculating speed limits. If the calculated route is different from the current route, the new route is returned through the navigationManager:didFindAlternateRoute: delegate callback. You can then set the new NMARoute to the NMANavigationManager manually by calling setRoute:.

The NMATrafficWarner Class

The NMATrafficWarner 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 NMATrafficWarner object, use the trafficWarner property from NMANavigationManager. You can then call the method start method on the NMATrafficWarner to initialize it.

To listen for traffic notifications, implement NMATrafficWarnerDelegate and the trafficWarner:didDetectTraffic: callback method.

One or more of the following methods can be used to operate traffic warner, or to retrieve a notification of a route:

  • isTrafficNotificationAhead: - determines whether or not a traffic notification is ahead of the last callback position
  • isTrafficNotification:onRoute: - determines if a traffic notification is on a given route
  • trafficNotificationOnCurrentRoute - retrieves the traffic notification for the route that is in use by the navigation manager
  • trafficNotificationOnRoute: - retrieves the traffic notification for the specified route
  • stop - stops the traffic warner

The NMATrafficNotification and NMATrafficNotificationInfo Classes

NMATrafficWarner.Listener provides a callback that returns a NMATrafficNotification object that is relevant to the current navigation session. This NMATrafficNotification contains a list of NMATrafficNotificationInfo instances associated with the traffic notification, retrievable through the trafficNotificationInfo property.

The NMATrafficNotificationInfo class encapsulates the details of a traffic notification. NMATrafficNotificationType defines the type of traffic notification with regards to the current route.

The following properties and methods can be used to retrieve details about a NMATrafficNotificationInfo instance:

  • type - the type of traffic notification info
  • severity - the severity of the current traffic notification event
  • affectedLength - the length, in meters, of the traffic notification event
  • distance - gets the distance from the current NMAPositioningManager position to the traffic notification

For more information, please consult the API Reference.

Alternative routes finding when traffic avoidance mode enabled

Called when the navigation manager has found alternative routes for current one during navigation.
Note: Please do not confuse navigationManager:didFindAlternateRoutes: and navigationManager:didFindAlternateRouteWithResult:. navigationManager:didFindAlternateRoutes: - optional routes. navigationManager:didFindAlternateRouteWithResult: - an improved route.
The following is an example of a navigationManager:didFindAlternateRoutes: implementation:
- (void) navigationManager:(nonnull NMANavigationManager*)navigationManager
  didFindAlternateRoutes:(nonnull NMARouteResult *)routeResult
  //** remove old alternative routes from current map if any
  [self.activeMapView removeMapObjects: self.alternativeRoutes];
  self.alternativeRoutes = [[NSMutableArray alloc] init];

  //** enumerate all available alternative routes
  for (NMARoute *route in routeResult.routes) {
    //** Instantiate new map route object
    NMAMapRoute *mapRoute = [[NMAMapRoute alloc] initWithRoute:route];

    //** Install random color for the one route
    mapRoute.color =
    [UIColor colorWithHue:drand48() saturation:1.0 brightness:1.0 alpha:1.0];

    //** Update internal storage
    [self.alternativeRoutes addObject:mapRoute];
    //** Show alternative route simultaneously with current guidance route
    [self.activeMapView addMapObject:mapRoute];