Car and Pedestrian Routing
The HERE iOS SDK supports route calculation with multiple waypoints, optimized for walking or driving.
- A line rendered on a map that displays a connecting path between all waypoints
- Turn-by-turn directions in text format
NMACoreRouter
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.
NMACoreRouter
supports routes with a maximum of 32 waypoints. NMACoreRouter
variables must be strongly referenced and retained (such as made into a class member). Otherwise, the object may go out of scope and be garbage collected. NMAWaypoint
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.
NMARoutingMode
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 theNMARoutingOption
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)
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. NMARoute
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.
NMARoute
object contains route information that can be accessed by calling one or more of the following methods: -
routingMode
- theNMARoutingMode
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
- theNMARouteTta
indicating the estimated time to arrival -
ttaWithTraffic
- theNMARouteTta
indicating the estimated time to arrival with traffic consideration -
boundingBox
- gets the smallestNMAGeoBoundingBox
that contains the entire route -
routeGeometry
- gets the array of allNMAGeoCoordinates
along the route -
mapPolyline
- gets theNMAMapPolyline
representation of the route
NMARouteTta
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
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;
NMAManeuver
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
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.
NMAMapRoute
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.
![]() | ![]() |
![]() |
For example, if you want to render a route that connects two waypoints (start and destination), you can add the following application logic:
NMAMapRoute
added to an NMAMapView

- Create a
NMACoreRouter
// Create a NMACoreRouter. NMACoreRouter* coreRouter = [[NMACoreRouter alloc] init];
- Create an
NSMutableArray
and add twoNMAGeoCoordinates
stopsNMAGeoCoordinates* 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];
- Create an
NMARoutingMode
and set itsNMATransportMode
,NMARoutingType
andNMARoutingOption
valuesNMARoutingMode* routingMode = [[NMARoutingMode alloc] initWithRoutingType:NMARoutingTypeFastest transportMode:NMATransportModeCar routingOptions:0];
- 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;
- 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 withAnimation:NMAMapAnimationLinear]; } else if (error) { // Display a message indicating route calculation failure } }];
Note: Routes are returned even if you receive theNMARoutingErrorViolatesOptions
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.
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. NMAMapView
is set to display traffic. However, calling requestTrafficOnRoute:
explicitly is recommended before retrieving traffic events using NMATrafficManager
. 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).
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 whileNMAApplicationContext
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.
Routing-related enumerations
- The
NMARoutingType
enum - represents values describing different routing types, such asNMARoutingTypeFastest
orNMARoutingTypeShortest
- The
NMATransportMode
enum - represents values describing different transport modes, such asNMATransportModeCar
orNMATransportModePedestrian
- The
NMARoutingOption
enum - represents values describing special conditions for route calculation, such asNMARoutingOptionAvoidBoatFerry
orNMARoutingOptionAvoidTollRoad
. 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 toNMARoutingOption
. 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 aNMARoute
with theNMARouteViolatedOptionBlockedRoad
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 ofNMARouteViolatedOptionBlockedRoad
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 asNMARoutingErrorNone
orNMARoutingErrorViolatesOptions