Car and Pedestrian Routing

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

Routing Example on GitHub

NMACoreRouter

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 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 dynamicPenalty property before launching a route calculation. For more information on the NMADynamicPenalty class see Dynamic Routing Penalty.

Note:NMACoreRouter variables must be strongly referenced and retained (e.g. 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

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 NMARoutingOption enums) applicable for this route

startDirection - the direction of travel that the route should start in. By default this is set to "any direction" 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 fewer than this limit)

Note: Routing type describes different optimizations that can be applied during the route calculation:

Fastest - route calculation from start to destination optimized by travel time. In some cases the route returned by the fastest mode may not be the route with the shortest possible travel time. For example, it may favor a route that remains on a highway even if a shorter travel time can be achieved by taking a detour or shortcut through a side road.

Shortest - route calculation from start to destination disregarding any speed information. In this mode the distance of the route is minimized while keeping the route sensible. This includes, for example, penalizing turns. Because of that the resulting route will not necessarily be the one with minimal distance.

Balanced - route calculation from start to destination optimizing based on combination of travel time and distance.

Note: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 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 calculateRouteWithStops:routingMode:completionBlock: method of NMACoreRouter triggers a route calculation while the returned NSProgress object and 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

ttaIncludingTrafficForSubleg - the NMARouteTta indicating the estimated time to arrival taking into account traffic conditions at the time of the route calculation

ttaUsingDownloadedTrafficForSubleg - the NMARouteTta indicating the estimated time to arrival with traffic conditions while the traffic conditions are taken from traffic data downloaded to the device

ttaExcludingTrafficForSubleg - the NMARouteTta indicating the estimated time to arrival without considering traffic conditions

routeGeometry - gets the array of all NMAGeoCoordinates along the route

mapPolyline - gets the NMAMapPolyline 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 tta property. For example,

Traffic-Aware Routing and NMARouteTta

The NMARoute class also provides ttaIncludingTrafficForSubleg and ttaUsingDownloadedTrafficForSubleg methods which provide a different set of NMARouteTta results that take traffic into account. If the route was originally calculated with setting a traffic penalty mode, ttaIncludingTrafficForSubleg method will return the estimated time to arrival with traffic conditions at the time of the route calculation. The value is calculated once at the time of route calculation and does not change with time. ttaUsingDownloadedTrafficForSubleg should be used in cases when the time elapsed since a route was returned is large enough to make the time to arrival (as obtained using ttaIncludingTrafficForSubleg) no longer accurate, given changing traffic conditions. ttaUsingDownloadedTrafficForSubleg will provide a more up-to-date time to arrival estimate provided traffic data has been constantly refreshed using the NMATrafficManager class.

Code snippet on how to use ttaIncludingTrafficForSubleg to get time to arrival considering traffic at the time the route was calculated.

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 an 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 an NMAMapRoute after a route calculation and adds the NMAMapRoute to the map by calling NMAMapView addMapObject:.

You can customize map route colors by using renderType property and NMAMapRoute APIs. There are three supported render type values: NMAMapRouteRenderTypePrimary, NMAMapRouteRenderTypeSecondary, and NMAMapRouteRenderTypeUserDefined. By default, an 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 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:

Note: Routes are returned even if you receive 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 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 trafficPenaltyMode property.

You can change the active policy by setting 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 requestTrafficOnRoute: method:

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 SDK for iOS are able to request routing information to assist travelling from one location to another.

Your application 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 California and Oregon states, a route from San Diego to Portland can be created without any data connection.

Note: In HERE SDK v3.4 we have updated the behavior of 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 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 NMAApplicationContext connectivity setting.

If you launch a request using the "offline" connectivity mode, an offline request is performed regardless of NMAApplicationContext connectivity setting.

In all cases if the request fails, no fallback action is automatically performed.

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

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 an NMARoute with 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.