HERE iOS SDK Developer's Guide

NMARoute

Class Summary

class NMARoute

Derived from: NSObject

Represents a path (a collection of maneuvers) connecting two or more waypoints.

Include: NMAKit.framework/headers/NMARoute.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMARoute

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties

[readable, assign] NMAUrbanMobilityArrival arrival

Information about arrival, see NMAUrbanMobilityArrival class for details

[readable, strong] NMAGeoBoundingBox boundingBox

The smallest NMAGeoBoundingBox that contains the entire NMARoute

[readable, assign] NSUInteger  changes

The number of times a public transport change is done on this route

[readable, assign] NMAUrbanMobilityDeparture departure

Information about departure, see NMAUrbanMobilityDeparture class for details

[readable, weak] NMAWaypoint destination

The destination NMAWaypoint for the NMARoute

[readable, assign] NSTimeInterval  duration

The duration in seconds of the route

[readable, strong] NSArray< NMAGeoCoordinates * > *  geometry

The NSArray of NMAGeoCoordinates representing, in order, the polyline of the route

[readable, strong] NSArray< NMAGeoCoordinates * > *  geometryWithElevationData

The NSArray of NMAGeoCoordinates (with elevation data, if available) representing, in order, the polyline of the route

[readable, assign] NSUInteger  length

The length of the NMARoute, in meters

[readable, strong] NSArray< NMAManeuver * > *  maneuvers

Array of NMAManeuver to represent all the maneuvers that travelers will encounter along the NMARoute

[readable, strong] NMAMapPolyline mapPolyline

Deprecated: This property is deprecated as of NMA SDK 3.3. This is replaced by geometry. NMAMapPolyline may be instantiated from geometry via "mapPolylineWithVertices:".

The NMAMapPolyline representation of the route

[readable, assign] NSArray< NSNumber * > *  permanentDirectedLinkIds

Array of permanent link ids of the NMARoadElement objects contained in this route with their travel directions

[readable, assign] NSArray< NSNumber * > *  permanentLinkIds

Array of permanent link ids of the NMARoadElement objects contained in this route

[readable, strong] NSArray< NMARouteElement * > *  routeElements

The list of NMARouteElement (or instances of classes derived from it) within the route object

[readable, assign] NSString *  routeId

A unique id for this route

[readable, strong] NMARoutingMode routingMode

The NMARoutingMode for the NMARoute

[readable, assign] NSArray< NMAUrbanMobilityRouteSection * > *  sections

Array of NMAUrbanMobilityRouteSection of the route

[readable, assign] NMATransitRouteSourceAttribution sourceAttribution

The transit information source attribution for the route.

[readable, weak] NMAWaypoint start

The starting NMAWaypoint for the NMARoute.

[readable, assign] NSUInteger  sublegCount

Returns the number of sub-legs the route has a subleg is the part of a route between two stop waypoints

[readable, assign] NSArray< NMAUrbanMobilityTariff * > *  tariffOptions

Array of NMAUrbanMobilityTariff representing different options you can purchase for just one route

[readable, assign] NMARouteTta tta

The NMARouteTta object of traveling the whole NMARoute

[readable, writable, strong] NSString *  userTag

[readable, strong] NSArray< NMAWaypoint * > *  waypoints

Array of NMAWaypoint for all waypoints of the NMARoute

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary

-(nullable NMARouteConsumption *) consumptionWithParameters:(nonnull NMARouteConsumptionParameters *) consumptionParameters dynamicPenalty:(nullable NMADynamicPenalty *) dynamicPenalty

Return the anticipated energy consumption for driving this route.

-(nonnull instancetype) init

NMARoute is generated from route calculation or route deserialization

-(nullable NMAGeoCoordinates *) lastReachablePositionWithConsumption:(nonnull NMARouteConsumption *) routeConsumption currentCapacity:(NSInteger) capacity

The last reachable waypoint given a specific consumption model.

-(void) serializedRouteWithCompletionBlock:(nonnull NMARouteSerializationCompletionBlock ) completionBlock

Serialize an NMARoute object asynchronously.

-(nullable NSData *) serializedRouteWithError:(NSError *_Nullable *_Nullable) error

Serialize an NMARoute object.

-(nullable NMARouteTta *) ttaForSubleg:(NSUInteger) subleg

The NMARouteTta object of traveling the specified subLeg of the NMARoute.

-(nullable NMARouteTta *) ttaWithTraffic:( NMATrafficPenaltyMode ) mode

The NMARouteTta object of traveling the the whole NMARoute with traffic consideration if traffic information is available.

-(nullable NMARouteTta *) ttaWithTraffic:( NMATrafficPenaltyMode ) mode forSubleg:(NSUInteger) subleg

The NMARouteTta object of traveling the the whole NMARoute with traffic consideration if traffic information is available.

Class Method Summary

Table 3. Class Methods
Class Methods

+(nonnull instancetype) new

NMARoute is generated from route calculation or route deserialization

+(nullable NMARoute *) routeFromSerializedRoute:(nonnull NSData *) data error:(NSError *_Nullable *_Nullable) error

Create an NMARoute from a previously serialized route.

+(void) routeFromSerializedRoute:(nonnull NSData *) data withCompletion:(nonnull NMARouteDeserializationCompletionBlock ) completionBlock

Create an NMARoute from a previously serialized route asynchronously.

Class Details

Represents a path (a collection of maneuvers) connecting two or more waypoints.

Waypoints may be thought of as the input to a route calculation whereas maneuvers are the results of calculating a route.

Public Property Details

[readable, assign] NMAUrbanMobilityArrivalarrival

Information about arrival, see NMAUrbanMobilityArrival class for details.

[readable, strong] NMAGeoBoundingBoxboundingBox

The smallest NMAGeoBoundingBox that contains the entire NMARoute.

[readable, assign] NSUInteger changes

The number of times a public transport change is done on this route.

[readable, assign] NMAUrbanMobilityDeparturedeparture

Information about departure, see NMAUrbanMobilityDeparture class for details.

[readable, weak] NMAWaypointdestination

The destination NMAWaypoint for the NMARoute.

[readable, assign] NSTimeInterval duration

The duration in seconds of the route.

[readable, strong] NSArray< NMAGeoCoordinates * > * geometry

The NSArray of NMAGeoCoordinates representing, in order, the polyline of the route.

No elevation profile of the route is available. The NMAGeoCoordinates altitude property will return -FLT_MAX (representing an unknown altitude).

[readable, strong] NSArray< NMAGeoCoordinates * > * geometryWithElevationData

The NSArray of NMAGeoCoordinates (with elevation data, if available) representing, in order, the polyline of the route.

An elevation profile of the route can be determined if the altitude property of the NMAGeoCoordinates does not return -FLT_MAX (representing an unknown altitude).

[readable, assign] NSUInteger length

The length of the NMARoute, in meters. This is the actual distance covered if you were to travel the route.

[readable, strong] NSArray< NMAManeuver * > * maneuvers

Array of NMAManeuver to represent all the maneuvers that travelers will encounter along the NMARoute. In case of calculation NMAUrbanMobilityRoute, this returns nil. Instead, you can find array of NMAUrbanMobilityManeuver in every NMAUrbanMobilityRoute::NMAUrbanMobilityRouteSectionWalk.

[readable, strong] NMAMapPolylinemapPolyline

Deprecated: This property is deprecated as of NMA SDK 3.3. This is replaced by geometry. NMAMapPolyline may be instantiated from geometry via "mapPolylineWithVertices:".

The NMAMapPolyline representation of the route.

[readable, assign] NSArray< NSNumber * > * permanentDirectedLinkIds

Array of permanent link ids of the NMARoadElement objects contained in this route with their travel directions. Will return empty array for offline calculated route or for public transport route. See also NMARoadElement::permanentDirectedLinkId

[readable, assign] NSArray< NSNumber * > * permanentLinkIds

Array of permanent link ids of the NMARoadElement objects contained in this route. Will return empty array for offline calculated route or for public transport route. See also NMARoadElement::permanentLinkId

[readable, strong] NSArray< NMARouteElement * > * routeElements

The list of NMARouteElement (or instances of classes derived from it) within the route object.

Note that if this is a transit route, this will be an array of NMATransitRouteElement. Otherwise, this is a list of NMARoadElement.

[readable, assign] NSString * routeId

A unique id for this route.

[readable, strong] NMARoutingModeroutingMode

The NMARoutingMode for the NMARoute.

[readable, assign] NSArray< NMAUrbanMobilityRouteSection * > * sections

Array of NMAUrbanMobilityRouteSection of the route. Can include different types NMAUrbanMobilityTransportType of transport, like walk or subway.

[readable, assign] NMATransitRouteSourceAttributionsourceAttribution

The transit information source attribution for the route.

In certain cases, data provided by Transit Agencies cannot be used without displaying copyright notices to the end user. The copyright information is provided in the source attribution objects and must be displayed together with a route. This requirement forms part of the terms and conditions of the API.

Note:

Source attribution may not be available in all cases.

[readable, weak] NMAWaypointstart

The starting NMAWaypoint for the NMARoute.

[readable, assign] NSUInteger sublegCount

Returns the number of sub-legs the route has a subleg is the part of a route between two stop waypoints.

[readable, assign] NSArray< NMAUrbanMobilityTariff * > * tariffOptions

Array of NMAUrbanMobilityTariff representing different options you can purchase for just one route.

[readable, assign] NMARouteTtatta

The NMARouteTta object of traveling the whole NMARoute.

Note:

The object returned will not include any delays due to traffic.

[readable, writable, strong] NSString * userTag

A user-defined tag to identify the NMARoute

Note:

The default value for userTag is empty string.

[readable, strong] NSArray< NMAWaypoint * > * waypoints

Array of NMAWaypoint for all waypoints of the NMARoute.

Instance Method Details

-(nullable NMARouteConsumption *) consumptionWithParameters:(nonnull NMARouteConsumptionParameters *) consumptionParameters dynamicPenalty:(nullable NMADynamicPenalty *) dynamicPenalty

Return the anticipated energy consumption for driving this route.

IMPORTANT: Consumption calculation is a Beta feature. The related classes and methods are subject to change without notice.

Parameters:

  • consumptionParameters

    Consumption parameters specific to the vehicle that is to drive the route

  • dynamicPenalty

    Restriction factors for a given area that will influence consumption. If there is no penalty in the route the value should be nil.

Returns:

NMARouteConsumption instance containing data about route consumption, or nil if the route type does not support consumption information (e.g. a transit route)

-(nullable NMAGeoCoordinates *) lastReachablePositionWithConsumption:(nonnull NMARouteConsumption *) routeConsumption currentCapacity:(NSInteger) capacity

The last reachable waypoint given a specific consumption model.

The NMARouteConsumption object passed to this method should have been previously obtained from the consumptionWithParameters:dynamicPenalty: method. In the case that consumptionWithParameters:dynamicPenalty: was called with the default values provided by NMARouteConsumptionParameters, an appropriate value for the capacity paramter would be 300000. This would represent a vehicle with maximum capacity. A lower value would correspond to a vehicle with lower remaining capacity which would not be able to travel as far.

IMPORTANT: Consumption calculation is a Beta feature. The related classes and methods are subject to change without notice.

Parameters:

  • routeConsumption

    Specifies the parameters of consumption for a given vehicle.

  • capacity

    Available capacity at the beginning of the route.

Returns:

the coordinates of the last reachable position.

-(void) serializedRouteWithCompletionBlock:(nonnull NMARouteSerializationCompletionBlock ) completionBlock

Serialize an NMARoute object asynchronously.

This method does not serialize invalid routes or routes calculated with NMATransportModePublicTransport or NMATransportModeUrbanMobility. Instead, nil is returned.

IMPORTANT: NMARoute serialization is a Beta feature. The related classes are subject to change without notice.

Parameters:

  • completionBlock

    the block to execute on completion of the serialization

-(nullable NSData *) serializedRouteWithError:(NSError *_Nullable *_Nullable) error

Serialize an NMARoute object.

This method does not serialize invalid routes or routes calculated with NMATransportModePublicTransport or NMATransportModeUrbanMobility. Instead, nil is returned. When serializing a route with many waypoints, post to GCD to avoid blockage on the main thread.

IMPORTANT: NMARoute serialization is a Beta feature. The related classes are subject to change without notice.

Parameters:

  • error

    nil if deserialization completed successfully, otherwise an NSError object with an NMARouteSerializationError indicating the failure reason.

-(nullable NMARouteTta *) ttaForSubleg:(NSUInteger) subleg

The NMARouteTta object of traveling the specified subLeg of the NMARoute.

Note:

The object returned will not include any delays due to traffic.

Parameters:

  • subleg

    The index of the subleg on the NMARoute to be used for this calculation. If NMARouteSublegWhole is provided, it is the same as tta property.

-(nullable NMARouteTta *) ttaWithTraffic:( NMATrafficPenaltyMode ) mode

The NMARouteTta object of traveling the the whole NMARoute with traffic consideration if traffic information is available.

This method returns a nil object if access to this operation is denied. Contact your HERE representative for more information.

To ensure ttaWithTraffic considers traffic for the ENTIRE route do either of the following:

(1) If you calculate your route with traffic, i.e. by specifying a traffic dynamic penalty via NMACoreRouter, then simply call ttaWithTraffic. IMPORTANT: In this case the returned NMARouteTta may indicate the route is not blocked even if it is. Always check NMARoutingViolatedOption of the result object in completion callback.

(2) If you calculate your route without traffic, but you are still interested in duration and details for your route with traffic, then you need to: a. Request traffic for the entire route, see "requestTrafficOnRoute:" in NMATrafficManager b. Wait for the callback "trafficDataDidFinish" to ensure the traffic data has been downloaded c. Get the duration with traffic by calling ttaWithTraffic.

In both of the above cases you must be online!

Please note that enabling traffic on NMAMapView (using any of the traffic related methods) will cause traffic data to be downloaded and hence considered by ttaWithTraffic. This can lead to situations in which ttaWithTraffic will only consider traffic for the visible part of the route if (1) or (2) above were not performed.

Parameters:

  • mode

    NMATrafficPenaltyMode to be used for this calculation.

-(nullable NMARouteTta *) ttaWithTraffic:( NMATrafficPenaltyMode ) mode forSubleg:(NSUInteger) subleg

The NMARouteTta object of traveling the the whole NMARoute with traffic consideration if traffic information is available.

This method returns a nil object if access to this operation is denied. Contact your HERE representative for more information.

To ensure ttaWithTraffic considers traffic for the ENTIRE route do either of the following:

(1) If you calculate your route with traffic, i.e. by specifying a traffic dynamic penalty via NMACoreRouter, then simply call ttaWithTraffic. IMPORTANT: In this case the returned NMARouteTta may indicate the route is not blocked even if it is. Always check NMARoutingViolatedOption of the result object in completion callback.

(2) If you calculate your route without traffic, but you are still interested in duration and details for your route with traffic, then you need to: a. Request traffic for the entire route, see "requestTrafficOnRoute:" in NMATrafficManager b. Wait for the callback "trafficDataDidFinish" to ensure the traffic data has been downloaded c. Get the duration with traffic by calling ttaWithTraffic.

In both of the above cases you must be online!

Please note that enabling traffic on NMAMapView (using any of the traffic related methods) will cause traffic data to be downloaded and hence considered by ttaWithTraffic. This can lead to situations in which ttaWithTraffic will only consider traffic for the visible part of the route if (1) or (2) above were not performed.

Parameters:

  • mode

    NMATrafficPenaltyMode to be used for this calculation.

  • subleg

    The index of the subleg on the NMARoute to be used for this calculation. If NMARouteSublegWhole is provided, it is the same as ttaWithTraffic property.

Class Method Details

+(nullable NMARoute *) routeFromSerializedRoute:(nonnull NSData *) data error:(NSError *_Nullable *_Nullable) error

Create an NMARoute from a previously serialized route.

This method returns nil if the deserialization fails. The deserialization fails when the map version from which the NMARoute was serialized does not match current map version, the SDK version from which the NMARoute was serialized is not compatible with current SDK version, or when the input data is invalid or corrupted. When deserializing a route with many waypoints, post to GCD to avoid blockage on the main thread.

IMPORTANT: NMARoute serialization is a Beta feature. The related classes are subject to change without notice.

Parameters:

  • data

    NSData to be deserialized into a NMARoute.

  • error

    nil if deserialization completed successfully, otherwise an NSError object with an NMARouteSerializationError indicating the failure reason.

+(void) routeFromSerializedRoute:(nonnull NSData *) data withCompletion:(nonnull NMARouteDeserializationCompletionBlock ) completionBlock

Create an NMARoute from a previously serialized route asynchronously.

This method passes nil to the callback if the deserialization fails. The deserialization fails when the map version from which the NMARoute was serialized does not match current map version, the SDK version from which the NMARoute was serialized is not compatible with current SDK version, or when the input data is invalid or corrupted.

IMPORTANT: NMARoute serialization is a Beta feature. The related classes are subject to change without notice.

Parameters:

  • data

    NSData to be deserialized into a NMARoute.

  • completionBlock

    the block to execute on completion of deserializtion