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

NMARouteManager

The NMARouteManager class is responsible for calculating an NMARoute using a list of stops and an NMARoutingMode. It also provides an NMARouteManagerDelegate protocol for monitoring calculation progress and triggering appropriate callback methods upon completion. To calculate a route, the application needs to call the calculateRouteWithStops:routingMode: method. NMARouteManager only supports one routing request at a time. Making another request before completion of the current request is not supported.

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

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 the NMARoutingOption enums) that are applicable for this 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.

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: method of NMARouteManager triggers a route calculation, while the NMARouteManagerDelegate implements callback methods 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
  • 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

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;
}

NMAManeuver

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.

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

Figure 1. An NMAMapRoute added to an NMAMapView

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

  1. Adopt NMARouteManagerDelegate protocol and create a NMARouteManager
    @interface ClassName : NSObject <NMARouteManagerDelegate>
    {
      // Setup your class
    }
    
    (void)setup
    {
      // Create a NMARouteManager.
      NMARouteManager* routeManager = [NMARouteManager sharedRouteManager];
    
      // Setup delegate
      [routeManager setDelegate:self];
    }
  2. Create an NSMutableArray and add two NMAGeoCoordinates stops
    NSMutableArray* stops = [[NSMutableArray alloc] initWithCapacity:4];
    NMAGeoCoordinates* geoCoord1 = [[NMAGeoCoordinates alloc]
    initWithLatitude:49.1966286 longitude:-123.0053635];
    NMAGeoCoordinates* geoCoord2 = [[NMAGeoCoordinates alloc]
    initWithLatitude:49.1947289 longitude:-123.1762924];
    [stops addObject:geoCoord1];
    [stops addObject:geoCoord2];
  3. Create an NMARoutingMode and set its NMATransportMode, NMARoutingType and NMARoutingOption values
    NMARoutingMode* routingMode = [[NMARoutingMode alloc]
        initWithRoutingType:NMARoutingTypeFastest
        transportMode:NMATransportModeCar
        routingOptions:0];
  4. Calculate the route
    [routeManager calculateRouteWithStops:stops routingMode:routingMode];
    
  5. To receive the results of the route calculation, implement the NMARouteManagerDelegate protocol method routeManager:didCalculateRoutes:withError:violatedOptions: in your delegate class.
    Note: Routes are returned even if you receive the NMARouteManagerErrorViolatesOptions error. It is up to you to handle these route results that violate routing options.
    -(void) routeManager: (NMARouteManager*)routeManager
      didCalculateRoutes:(NSArray*)routes
      withError:(NMARouteManagerError)error
      violatedOptions:(NSArray*)violatedOptions
    {
      // If the route was calculated successfully
      if (!error && routes && routes.count > 0)
      {
        NMARoute* route = [routes objectAtIndex:0];
        // Render the route on the map
        NMAMapRoute *mapRoute = [NMAMapRoute mapRouteWithRoute:route];
        [mapView addMapObject:mapRoute];
      }
      else if (error)
      {
        // Display a message indicating route calculation failure
      }
    }

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.
  • The NMARouteManagerError enum - represents values describing possible route calculation errors, such as NMARouteManagerErrorNone or NMARouteManagerErrorViolatesOptions