RoutingEngine

public class RoutingEngine : RoutingProtocol
extension RoutingEngine: NativeBase
extension RoutingEngine: Hashable

Use the RoutingEngine to calculate a route from A to B with a number of waypoints in between.

Route calculation is done asynchronously and requires an online connection. The resulting route contains various information such as the polyline, route length in meters, estimated time to traverse along the route and maneuver data.

Note: The engine does not support an unlimited number of waypoints. The limit is defined by the HERE backend services and may change. For now, the maximum number of waypoints should be below 200. This value may change and it is not guaranteed to be stable. If you need to support very large lists of waypoints, consider to import a route (see importRoute() method) or use the OfflineRoutingEngine which supports an unlimited number of waypoints. The OfflineRoutingEngine is only available for Navigate licence.

  • Creates a new instance of this class.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init() throws

  • Creates a new instance of RoutingEngine.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init(_ sdkEngine: SDKNativeEngine) throws

    Parameters

    sdkEngine

    An SDKEngine instance.

  • Creates a new instance of RoutingEngine.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init(connectionSettings: RoutingConnectionSettings) throws

    Parameters

    connectionSettings

    Settings for the route calculation.

  • Creates a new instance of RoutingEngine.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init(_ sdkEngine: SDKNativeEngine, connectionSettings: RoutingConnectionSettings) throws

    Parameters

    sdkEngine

    An SDKEngine instance.
    connectionSettings

    Settings for the route calculation.

  • Asynchronously calculates a route from one point to another, passing through the given waypoints in the given order.

    Declaration

    Swift

    @discardableResult
public func calculateRoute(with waypoints: [Waypoint], options: RoutingOptions, completion: @escaping CalculateRouteCompletionHandler) -> TaskHandle

    Parameters

    waypoints

    The list of waypoints used to calculate the route. The first element marks the starting position, the last marks the destination. Waypoints in between are interpreted as intermediate.
    options

    Options describing routing options.
    completion

    Callback object that will be invoked after route calculation. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously calculates a new route that leads back to the original route. The part of the original route which was already traveled by the user is ignored.

    Note: Stopover waypoints are guaranteed to be visited. Pass-through waypoints will be ignored. Additionally, the following route options are ignored: RouteOptions.alternatives, RouteOptions.arrivalTime, and RouteOptions.optimizationMode. Most route options are only applied to the newly calculated part back to the route.

    An application may use this method to submit a new starting point for a previously calculated route. This method tries to avoid a costly route re-calculation as much as possible. In case returning to the route without re-calculation is not possible, a new route is calculated, while trying to salvage the previous route as much as possible. However, a completely new route containing no part of the previous route is possible, too.

    Note that this function uses only a limited amount of map data around the new origin. Therefore, it may also work fine with temporarily cached map data. It may also copy some of the original route data into the new route.

    A typical use case is to await at least 3 RouteDeviation events before calling this method.

    • Or alternatively, wait at least 10 seconds after getting the first deviation event.
    • On top, the user experience can be improved by checking if the vehicle has moved at least 50 meters since calling this method for the last time.
    • Optionally, it may make sense to verify if the vehicle was ever following the route by checking if RouteDeviation.lastLocationOnRoute is set.

    Note that deviation events are sent each time a deviation is detected, i.e. for each new location update, regardless if the location has changed or not. More information can be found in the Developer Guide in the “Handle route deviations” section.

    Declaration

    Swift

    @discardableResult
public func returnToRoute(_ route: Route, startingPoint: Waypoint, lastTraveledSectionIndex: Int32, traveledDistanceOnLastSectionInMeters: Int32, completion: @escaping CalculateRouteCompletionHandler) -> TaskHandle

    Parameters

    route

    A Route calculated using the online or offline route engine. For the offline case, It should not contain an indoor Section as such routes will fail. For the online case, it should have RouteHandle.
    startingPoint

    The current location, for example, provided by a RouteDeviation event. The waypoint needs to be of type WaypointType.stopover. Otherwise, an RoutingError.invalidParameter error is generated.
    lastTraveledSectionIndex

    Indicates the index of the last traveled route section. Traveled part of the route won’t be reused.
    traveledDistanceOnLastSectionInMeters

    Offset in meter to the last visited position on the route section defined by the last traveled section index.
    completion

    Callback object that will be invoked after route calculation. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously refreshes a previously calculated route from the provided RouteHandle, updating the starting point and route metadata based on RoutingOptions. The route shape from the new starting point to the destination remains unchanged, and only metadata such as arrival time and traffic delays are updated.

    Declaration

    Swift

    @discardableResult
public func refreshRoute(refreshRouteParameters: RefreshRouteParameters, routingOptions: RoutingOptions, completion: @escaping CalculateRouteCompletionHandler) -> TaskHandle

    Parameters

    refreshRouteParameters

    The parameters used to refresh the route
    routingOptions

    The options define the vehicle and route options used to calculate the route.
    completion

    Callback object that will be invoked after refreshing the route. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously creates a route from a sequence of geographic coordinates very close to each other. The route shape will be kept as close as possible to the one provided. For best results please use 1Hz GPS data, or geographic coordinates that have a spacing of a few meters one from the other. For example, such a list of geographic coordinates can be extracted from a GPX trace or a route object from a 3rd party library. Very sparse data may be rejected by the service with an error.

    Note: Any restrictions applied to a transport type or provided options will be discarded and reported as violations in Section.sectionNotices.

    Declaration

    Swift

    @discardableResult
public func importRoute(with locations: [Location], options: RoutingOptions, completion: @escaping CalculateRouteCompletionHandler) -> TaskHandle

    Parameters

    locations

    The list of locations used to calculate the route. Note that only the Location.coordinates of a location are used to import the route.
    options

    The options define the vehicle and route options to calculate the route.
    completion

    Callback object that will be invoked after route calculation. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously creates a route from a sequence of geographic coordinates very close to each other. The route shape will be kept as close as possible to the one provided. For best results please use 1Hz GPS data, or geographic coordinates that have a spacing of a few meters one from the other. For example, such a list of geographic coordinates can be extracted from a GPX trace or a route object from a 3rd party library. Very sparse data may be rejected by the service with an error.

    Note: Any restrictions applied to a transport type or provided options will be discarded and reported as violations in Section.sectionNotices .

    Declaration

    Swift

    @discardableResult
public func importRoute(with locations: [Location], routeStops: [RouteStop], options: RoutingOptions, completion: @escaping CalculateRouteCompletionHandler) -> TaskHandle

    Parameters

    locations

    The list of locations used to calculate the route. Note that only the Location.coordinates of a location are used to import the route.
    routeStops

    The list of RouteStop’s which contains index of location from locations list used for route stop and duration in seconds spent on stop.
    options

    The options define the vehicle and route options to calculate the route.
    completion

    Callback object that will be invoked after route calculation. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously recreates a route from the RouteHandle provided, i.e. refreshes a previously calculated route, with the specified RoutingOptions.

    A route handle can be invalid when the map data changes that is used by the HERE sdk to recreate the route. This happens regularly. Therefore, the route handle is not meant to be persisted for a longer time.

    Declaration

    Swift

    @discardableResult
public func importRoute(routeHandle: RouteHandle, options: RoutingOptions, completion: @escaping CalculateRouteCompletionHandler) -> TaskHandle

    Parameters

    routeHandle

    The route handle holding the route to be refreshed.
    options

    The options define the vehicle and route options to calculate the route.
    completion

    Callback object that will be invoked after refreshing the route. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously calculates the traffic along a route starting from the index of the last traveled route section and an offset (in meters) from the last visited position on the section. Call this when only the contained traffic information or the latest ETA duration is needed. This can be called periodically to retrieve updated ETA values during navigation.

    Note: Calling this method will trigger a new “HERE Traffic” transaction, for example, if you are using the Base Plan.

    Declaration

    Swift

    public func calculateTrafficOnRoute(route: Route, lastTraveledSectionIndex: Int32, traveledDistanceOnLastSectionInMeters: Int32, completion: @escaping CalculateTrafficOnRouteCompletionHandler) -> TaskHandle

    Parameters

    route

    A Route calculated using the online routing engine. Its RouteHandle and the original route calculation options will be used to compute the traffic on the route. The original route remains untouched.
    lastTraveledSectionIndex

    Indicates the index of the last traveled route section. Traveled part of the route won’t be reused.
    traveledDistanceOnLastSectionInMeters

    Offset, in meters, to the last visited position on the route section defined by the last traveled section index.
    completion

    Callback object that will be invoked after route traffic has been calculated. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Asynchronously calculates the traffic along an EV car route starting from the index of the last traveled route section and an offset in meters from the last visited position on the section. The field TrafficOnSpan.consumptionInKilowattHours will contain the power consumption in kilowatt-hours (kWh) necessary to traverse the span, and RoutePlace.chargeInKilowattHours, inside TrafficOnSection.departurePlace and TrafficOnSection.arrivalPlace, the estimated battery charge in kilowatt-hours (kWh) when leaving/arriving to a section. Note: Only EV cars are supported.

    Declaration

    Swift

    public func calculateTrafficOnRoute(route: Route, lastTraveledSectionIndex: Int32, traveledDistanceOnLastSectionInMeters: Int32, currentChargeInKilowattHours: Double, completion: @escaping CalculateTrafficOnRouteCompletionHandler) -> TaskHandle

    Parameters

    route

    A Route calculated using the online routing engine. Its RouteHandle and the original route calculation options, along with EV related information like BatterySpecifications, will be used to compute the traffic on the route. The original route remains untouched.
    lastTraveledSectionIndex

    Indicates the index of the last traveled route section. Traveled part of the route won’t be reused.
    traveledDistanceOnLastSectionInMeters

    Offset, in meters, to the last visited position on the route section defined by the last traveled section index.
    currentChargeInKilowattHours

    Charge level of the vehicle’s battery at the current location (in kWh). It must be non-negative and less than or equal to the value of BatterySpecifications.totalCapacityInKilowattHours, otherwise the BatterySpecifications instance is considered invalid. Sets BatterySpecifications.initialChargeInKilowattHours to the given value.
    completion

    Callback object that will be invoked after route traffic has been calculated. It is always invoked on the main thread.

    Return Value

    Handle that will be used to manipulate the execution of the task.

  • Sets a custom option for routing backend queries. The custom option is applied to all the queries that RoutingEngine performs. For a complete list of available parameter names and their valid values, refer to HERE Routing API v8. Note: It’s easy to set a wrong option that makes queries invalid, so make sure you read and understand the backend documentation.

    Declaration

    Swift

    public func setCustomOption(name: String, value: String?) -> RoutingError?

    Parameters

    name

    An option name. If the engine already has an option with the same name, the option will be overwritten. The option name must be a non-empty string.
    value

    An option value. If the value is nil, the option will be removed. The option value must be a non-empty string.

    Return Value

    An optional error of setting the option. It’s nil if the option has been set successfully. It’s RoutingError.INVALID_PARAMETER if the input name and/or value haven’t passed internal validation.