SDK for iOS Developer's Guide

Traffic-Aware Navigation

With HERE SDK developers can enable turn-by-turn route navigation that takes live traffic information into account. 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 NMATrafficAvoidanceDisabled.

NMATrafficAvoidanceDisabled - Disables use of traffic for rerouting purpose.
In this mode the giudace engine disableas use of traffic for rerouting purpose, which means that online traffic information is not taken into account while rerouting. The live traffic data is not considered by NavigationManager unless setTrafficAvoidanceMode is enabled.
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 navigationManager:didUpdateRoute: delegate method.

Note: You can set the frequency of the route request by using setRouteRequestInterval:.
NMATrafficAvoidanceManual - Provides 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.

Manual Traffic-Based Rerouting

If the device is online and 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 navigationManger:didChangeRoutingState: method in NMANavigationManagerDelegate and checking for the state change from NMATrafficEnabledRoutingStateOn or NMATrafficEnabledRoutingStateNotAvilable to NMATrafficEnabledRoutingStateOngoingRequest.

Note: 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 navigationManager:didFindAlternateRoute: delegate callback. You can then set the new NMARoute to the NMANavigationManager manually by calling setRoute:.

NMATrafficWarner Class

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

To listen for traffic notifications, implement NMATrafficWarnerDelegate and 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

NMATrafficNotification and NMATrafficNotificationInfo Classes

NMATrafficWarner.Listener provides a callback that returns an 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 trafficNotificationInfo property.

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 an NMATrafficNotificationInfo instance:

type - the type of traffic notification info
severity - severity of the current traffic notification event
affectedLength - length, in metres, 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.

Finding Alternative Routes with Traffic Avoidance Mode Enabled

It is 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 an 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];
  }
}