HERE iOS SDK Developer's Guide

Car and Pedestrian Routing

The HERE iOS SDK supports route calculation with multiple waypoints, optimized for walking or driving.

A route describes a path between at least two waypoints, the starting point and the destination, with optional intermediate waypoints in between. Applications can provide route information to users in two ways:
  • A line rendered on a map that displays a connecting path between all waypoints
  • Turn-by-turn directions in text format


The NMACoreRouter class is responsible for calculating an NMARoute using a list of stops and an NMARoutingMode. It also provides an NMACalculateResultBlock for monitoring calculation progress and triggering appropriate callback methods upon completion. To calculate a route, call the calculateRouteWithStops:routingMode:completionBlock: method. You can launch parallel routing requests by using separate NMACoreRouter instances to launch calculation requests.

The NMACoreRouter can also calculate routes with traffic taken into account by setting the dynamicPenalty property before launching a route calculation. For more information on the NMADynamicPenalty class, see Dynamic Routing Penalty.

Note: NMACoreRouter supports routes with a maximum of 32 waypoints.


The NMACoreRouter supports waypoints as NMAPlace, NMAPlaceLocation, or NMAWaypoint objects.

You can use NMAWaypoint to add more waypoint details to a car route calculation. These details include whether a waypoint is a deliberate stopover or a via point that the route must pass through. This affects routing, as routes containing stopovers or via waypoints may be different. For example, a calculated route may suggest a U-turn maneuver after a stopover, while a route containing the same location as a via waypoint suggests continuing on the same street. The via waypoint type is only supported in car routes, and it is not supported in other route types.


The NMARoutingMode class is a model of the parameters required to calculate an NMARoute, such as:
  • routingType - the routing type, such as Fastest or Shortest
  • transportMode - the mode of transportation
  • routingOptions - the routing options (represented by the NMARoutingOption enums) that are applicable for this route
  • startDirection - the direction of travel that the route should start in. By default, this is set to "any direction" in order to achieve the fastest possible route.
  • departureTime - the departure time for the route
  • resultLimit - the maximum number of alternate routes to calculate (the actual number of results may be less than this limit)
Note: The HERE SDK allows for more than one route to be returned from a route calculation between two waypoints. You can use the NMARoutingMode class to set the desired number of routes, and the HERE SDK then returns different routes according to this limit. Note that the first element of the returned array is the best result based on the routing options, and the rest of the returned routes are not listed in any specific order.


The NMARoute class represents a distinct calculated path connecting two or more waypoints, and consists of a list of maneuvers and route links. A call to the calculateRouteWithStops:routingMode:completionBlock: method of NMACoreRouter triggers a route calculation, while the returned NSProgress object and the NMACalculateResultBlock block can be used to monitor the operation and process the resulting NMARoute objects.

An NMARoute object contains route information that can be accessed by calling one or more of the following methods:
  • routingMode - the NMARoutingMode for the route
  • waypoints - the array of all waypoints for the route
  • start - the starting waypoint for the route
  • destination - the destination waypoint for the route
  • maneuvers - the array of maneuvers for the route
  • length - the length of the route, in meters
  • tta - the NMARouteTta indicating the estimated time to arrival
  • ttaWithTraffic - the NMARouteTta indicating the estimated time to arrival with traffic consideration
  • boundingBox - gets the smallest NMAGeoBoundingBox that contains the entire route
  • routeGeometry - gets the array of all NMAGeoCoordinates along the route
  • mapPolyline - gets the NMAMapPolyline representation of the route


The NMARouteTta ("time-to-arrival") class provides useful information about the route, such as duration and route details that impact travel duration, including car pool restrictions, turn restrictions, and blocked roads. For example, to retrieve a duration for a calculated route, use the tta property. For example,

NSTimeInterval duration = route.tta.duration;

You can also retrieve the duration for a subleg from a route by using the ttaForSubleg: method. For example,

if (myRoute.sublegCount > 0)
  NSTimeInterval duration = [myRoute ttaForSubleg:0].duration;

Traffic-Aware Routing and NMARouteTta

The NMARoute class also provides the ttaWithTraffic property and the ttaWithTrafficForSubleg: method which provide a different set of NMARouteTta results that take the traffic into account. In order for these results to be populated, traffic information must be available, and you must specify the traffic feature before calculating a route by setting the dynamicPenalty property in NMACoreRouter. For example:
NMADynamicPenalty *penalty = [[NMADynamicPenalty alloc] init];
penalty.trafficPenaltyMode = NMATrafficPenaltyModeOptimal;
coreRouter.dynamicPenalty = penalty;
[coreRouter calculateRouteWithStops:stops routingMode:routingMode
  completionBlock:^(NMARouteResult *routeResult, NMARoutingError error) { ... }];

If you have calculated a route without first enabling traffic in RoutingMode, you can also perform the following to request for traffic data to be populated:

[[NMATrafficManager sharedTrafficManager] requestTrafficOnRoute:route];
//  Wait for the callback that the traffic data has been downloaded: trafficDataDidFinish.
NSTimeInterval durationWithTraffic = route.ttaWithTraffic.duration;
Note: A traffic-aware route calculation may return more violated options. For more information, see Routing-related enumerations and the API Reference.


The NMAManeuver class represents the action required to go from one segment to the next within a calculated NMARoute. Each NMAManeuver object provides information such as:
  • location of the maneuver
  • action required to complete the maneuver
  • distance between maneuvers
  • current road
  • next road
  • estimated times of the maneuver
  • highway signpost (if any) indicating entrance, exit, or merge information
  • a list of route elements representing portions of this maneuver
For more information, please consult the API Reference.

NMARouteElement and NMARoadElement

NMARouteElement and NMARoadElement represent portions within a maneuver. For example, a maneuver may ask the driver to turn left and then remain on a street, but this street may be comprised of multiple sections, including a tunnel, a dirt road, and a toll road. In this situation, the maneuver contains multiple NMARouteElement objects, with each element containing a NMARoadElement property that can provide your application with information about the individual section of the road.


The NMAMapRoute class is a type of NMAMapObject that displays a calculated route on a map. Typically, an application creates a NMAMapRoute after a route calculation, and add the NMAMapRoute to the map by calling NMAMapView addMapObject:.

You can customize map route colors by using the renderType property and NMAMapRoute APIs. There are three supported render type values: NMAMapRouteRenderTypePrimary, NMAMapRouteRenderTypeSecondary, and NMAMapRouteRenderTypeUserDefined. By default, a NMAMapRoute is set to the Primary set of pre-defined colors, and the secondary render type is designed to denote alternate routes. By using NMAMapRouteRenderTypeUserDefined, you can use the color and traveledColor properties and set the route colors to any ARGB color.

Figure 1. Using Primary RenderType
Figure 2. Using Secondary RenderType
Figure 3. User-Defined Route Color

For example, if you want to render a route that connects two waypoints (start and destination), you can add the following application logic:

Figure 4. An NMAMapRoute added to an NMAMapView
  1. Create a NMACoreRouter
    // Create a NMACoreRouter.
    NMACoreRouter* coreRouter = [[NMACoreRouter alloc] init];
  2. Create an NSMutableArray and add two NMAGeoCoordinates stops
    NMAGeoCoordinates* geoCoord1 = [[NMAGeoCoordinates alloc] initWithLatitude:49.1966286 longitude:-123.0053635];
    NMAGeoCoordinates* geoCoord2 = [[NMAGeoCoordinates alloc] initWithLatitude:49.1947289 longitude:-123.1762924];
    NMAWaypoint* waypoint1 = [[NMAWaypoint alloc] initWithGeoCoordinates:geoCoord1];
    NMAWaypoint* waypoint2 = [[NMAWaypoint alloc] initWithGeoCoordinates:geoCoord2];
    NSMutableArray* stops = [[NSMutableArray alloc] initWithCapacity:4];
    [stops addObject:waypoint1];
    [stops addObject:waypoint2];
  3. Create an NMARoutingMode and set its NMATransportMode, NMARoutingType and NMARoutingOption values
    NMARoutingMode* routingMode = [[NMARoutingMode alloc]
  4. If you want to calculate the route while taking traffic conditions into account, set the following flag:
    NMADynamicPenalty *penalty = [[NMADynamicPenalty alloc] init];
    penalty.trafficPenaltyMode = NMATrafficPenaltyModeOptimal;
    coreRouter.dynamicPenalty = penalty;
  5. Calculate the route and receive the results of the route calculation.
    [coreRouter calculateRouteWithStops:stops routingMode:routingMode
        completionBlock:^(NMARouteResult *routeResult, NMARoutingError error) {
          // If the route was calculated successfully
          if (!error && routeResult && routeResult.routes.count > 0)
            NMARoute* route = [routeResult.routes objectAtIndex:0];
            // Render the route on the map
            NMAMapRoute* mapRoute = [NMAMapRoute mapRouteWithRoute:route];
            [mapView addMapObject:mapRoute];
            // In order to see the entire route, we orientate the map view
            // accordingly
            [mapView setBoundingBox:route.boundingBox
          else if (error)
            // Display a message indicating route calculation failure
    Note: Routes are returned even if you receive the NMARoutingErrorViolatesOptions error. It is up to you to handle these route results that violate routing options.

Dynamic Routing Penalty

You can use NMADynamicPenalty to create a policy of roads and area restriction factors that are applied during routing calculations. For example, you can use this class to indicate that the travel speed in an area is 50 percent slower than usual. The NMADynamicPenalty class also allows you to set the mode used for handling traffic events in a route calculation through the trafficPenaltyMode property.

You can change the active policy by setting the dynamicPenalty property in NMACoreRouter. The policy must be set before a route calculation for the restrictions to be taken into account.

Retrieving Traffic Event Objects

You can use the NMATrafficManager class to retrieve traffic events, such as road closures or congestions. This is useful if your app needs to display a list of current traffic events for a given route.

Using NMATrafficManager is a two-step process. First, retrieve the events on the desired route using the requestTrafficOnRoute: method:
NSNumber *requestID = [[NMATrafficManager sharedTrafficManager] requestTrafficOnRoute:myRoute];
The requestTrafficOnRoute: method launches an asynchronous request to download the current traffic data to your device.
Note: Traffic data is also periodically downloaded when NMAMapView is set to display traffic. However, calling requestTrafficOnRoute: explicitly is recommended before retrieving traffic events using NMATrafficManager.
Upon the successful trafficDataDidFinish callback, you can retrieve a list of traffic events that affect the given route or route element by using one of the following methods:
  • getTrafficEventsOnRoute:withCompletion:
  • getTrafficEventsOnRouteElements:withCompletion:

Offline Routing

Even without an active data connection, applications developed with the HERE iOS SDK are able to request routing information to assist travelling from one location to another.

Your application's users do not need to maintain an active data connection to calculate routes and render them on a map. It is possible to pre-download updated maps and database information for performing routing requests while offline. For example, if a user has downloaded offline maps of the states California and Oregon, a route from San Diego to Portland can be created without any data connection.

For more information about downloading offline maps, refer to Offline Maps (Map Loader).

Note: In HERE SDK v3.4, we have updated the behavior of the routing connectivity modes (NMARequestConnectivity) to be more consistent with other parts of the SDK.
  • If you launch a request using the "default" connectivity mode, the request is performed according to the NMAApplicationContext connectivity setting. If the device is offline while NMAApplicationContext is set to online mode, the request fails.
  • If you launch a request using the "online" connectivity mode, an online request is performed, regardless of the NMAApplicationContext connectivity setting.
  • If you launch a request using the "offline" connectivity mode, an offline request is performed, regardless of the NMAApplicationContext connectivity setting.
In all cases, if the request fails, no fallback action is automatically performed.

Routing-related enumerations

Route calculations make use of HERE SDK enumerations that include:
  • The NMARoutingType enum - represents values describing different routing types, such as NMARoutingTypeFastest or NMARoutingTypeShortest
  • The NMATransportMode enum - represents values describing different transport modes, such as NMATransportModeCar or NMATransportModePedestrian
  • The NMARoutingOption enum - represents values describing special conditions for route calculation, such as NMARoutingOptionAvoidBoatFerry or NMARoutingOptionAvoidTollRoad. Values from this enum are also returned after a route calculation to indicate the options that a route result violates.
  • The NMARouteViolatedOption enum - represents values describing special conditions that are violated in a route calculation in addition to NMARoutingOption. This enum contains values for blocked roads and turn restrictions. For example, after specifying a route calculation that avoids tolls and ferries, you may get a NMARoute with the NMARouteViolatedOptionBlockedRoad violated option. This indicates that although a route was found, this route goes through at least one blocked road—violating a condition of your route request.
    Note: The absence of NMARouteViolatedOptionBlockedRoad does not necessarily indicate that no roads are blocked on a route. This is especially true when traffic information is unavailable or not enabled in the route calculation.
  • The NMARoutingError enum - represents values describing possible route calculation errors, such as NMARoutingErrorNone or NMARoutingErrorViolatesOptions