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.

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

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.

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

...
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

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.

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]
       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 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 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.

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

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 Preloading Map Data.

Routing-related enumerations