Car and Pedestrian Routing

Routing Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/ (Obj-C) and https://github.com/heremaps/ (Swift).

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.

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 pass-through point that the route must pass through. This affects routing, as routes containing stopovers or pass-through 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 pass-through waypoint suggests continuing on the same street. The pass-through waypoint type is only supported in car routes and it is not supported in other route types.

NMARoutingMode

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.

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,

NSTimeInterval duration = [route ttaExcludingTrafficForSubleg:NMARouteSublegWhole].duration;

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

if (myRoute.sublegCount > 0)
{
  NSTimeInterval duration = [myRoute ttaExcludingTrafficForSubleg:0].duration;
}

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.

...
NMADynamicPenalty *penalty = [[NMADynamicPenalty alloc] init];
penalty.trafficPenaltyMode = NMATrafficPenaltyModeOptimal;
coreRouter.dynamicPenalty = penalty;
[coreRouter calculateRouteWithStops:stops routingMode:routingMode
  completionBlock:^(NMARouteResult *routeResult, NMARoutingError error) { ... }];
NSTimeInterval duration = [route ttaIncludingTrafficForSubleg:NMARouteSublegWhole].duration;

If you have to calculate duration based on downloaded traffic data, 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 ttaUsingDownloadedTrafficForSubleg:NMARouteSublegWhole].duration;

NMAManeuver

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:

Figure 4. An NMAMapRoute added to an NMAMapView

1. Create an 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]
       initWithRoutingType:NMARoutingTypeFastest
       transportMode:NMATransportModeCar
       routingOptions:0];

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];
   
           // To see the entire route, we orient 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 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.

NSNumber *requestID = [[NMATrafficManager sharedTrafficManager] requestTrafficOnRoute:myRoute];

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.

For more information about downloading offline maps refer to Preloading Map Data.

Routing-Related Enumerations