SDK for iOS Developer's Guide

Car and Pedestrian Routing

SDK for iOS 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 calculateRouteWithStops:routingMode: method. NMARouteManager only supports one routing request at a time. Making another request before completion of the current request is not supported.

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
  • 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.
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: method of NMARouteManager triggers a route calculation while 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 tta property. For example,

NSTimeInterval duration = route.tta.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 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 time 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 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:.

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 an 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 NMARouteManagerDelegate protocol method routeManager:didCalculateRoutes:withError:violatedOptions: in your delegate class.
    Note: Routes are returned even if you receive 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:
  • NMARoutingType enum - represents values describing different routing types such as NMARoutingTypeFastest or NMARoutingTypeShortest
  • NMATransportMode enum - represents values describing different transport modes such as NMATransportModeCar or NMATransportModePedestrian
  • 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.
  • NMARouteManagerError enum - represents values describing possible route calculation errors such as NMARouteManagerErrorNone or NMARouteManagerErrorViolatesOptions