MapMatcher

public class MapMatcher
extension MapMatcher: NativeBase
extension MapMatcher: Hashable

This class provides map-matching functionality. It determines whether a location can be matched to a nearby road network and provides additional OCM map data for that location.

Note: This is a beta release of this feature. There may be bugs and unexpected behaviors. Related APIs may change in future releases without a deprecation process.

A MapMatcher maintains an internal state across location updates. This helps to check if the match is consistent with previous matches or if an unrealistic jump occurred due to low accuracy of the provided location.

A MapMatcher requires OCM tile data, either through caching, prefetching, or installed Region data. If the necessary tiles are not found, an online request is initiated. Note that in such cases, the download is triggered silently in the background, and nil is returned immediately.

The MapMatcher supports two layer configurations for retrieving segment geometry data:

  • Rendering layer (LayerConfiguration.Feature.RENDERING): Enabled by default. If your application uses map rendering or MapView components, using this layer is recommended.

  • eHorizon layer (LayerConfiguration.Feature.EHORIZON): Not enabled by default. It encodes segment geometries outside the rendering layer groups to reduce the amount of downloaded data. Use the eHorizon layer when:

    • No MapView is used in your application.
    • Only the eHorizon layer is used in your application. In these cases, using the eHorizon layer will reduce the required data to download. If the rendering layer is enabled, it will increase the required data to download.

Important: If useRenderingLayers is set to false without properly enabling the eHorizon layer, it may produce incorrect results. Layer configuration is especially important when prefetching or installing region data. Missing data will be downloaded online automatically as needed.

If your hardware supports pitch and high precision altitude information and you want to use them in the MapMatcher to improve map-matching, then enable the LayerConfiguration.Feature.ADAS layer:

  1. Turn on the ADAS layer via LayerConfiguration.enabledFeatures (it will increase data consumption).
  2. If available, set location.pitchInDegrees, location.coordinates.altitude and location.verticalAccuracyInMeters.
  3. In case of issues, please contact your HERE representative.

  • 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 this class.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init(sdkEngine: SDKNativeEngine) throws

    Parameters

    sdkEngine

    A SDKEngine instance.

  • Creates a new instance of this class.

    Throws

    InstantiationError Indicates what went wrong when the instantiation was attempted.

    Declaration

    Swift

    public init(sdkEngine: SDKNativeEngine, useRenderingLayers: Bool) throws

    Parameters

    sdkEngine

    A SDKEngine instance.
    useRenderingLayers

    When set to true, LayerConfiguration.Feature.RENDERING is used; otherwise, LayerConfiguration.Feature.EHORIZON is used to retrieve segment geometry data from the OCM map. Note: Ensure the corresponding layer is properly enabled in your LayerConfiguration to avoid incorrect results.

  • This method computes the map-matched location for the provided input location.

    Currently, matching is performed within a 50-meter radius of the provided location. If no road network is found within that radius, nil is returned.

    It’s required to set time field for each Location object for the MapMatcher to work properly. In case no time is provided, nil is returned and an error message is logged. It is used to calculate the distance in time between consecutive matches. Together with speed, this allows to calculate how likely a match is consistent with a previous match. To improve matching accuracy, it is recommended to provide bearing and speed parameters for each Location object.

    Declaration

    Swift

    public func match(location: Location) -> MapMatchedLocation?

    Parameters

    location

    The input location.

    Return Value

    map-matched location or nil if the location could not be matched to a road network.