Package com.here.sdk.mapmatcher

Class MapMatcher

java.lang.Object
com.here.NativeBase
com.here.sdk.mapmatcher.MapMatcher
public final class MapMatcher extends NativeBase

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

  • Constructor Details

    • MapMatcher

      public MapMatcher() throws InstantiationErrorException

      Creates a new instance of this class.

      Throws:
      InstantiationErrorException -

      Indicates what went wrong when the instantiation was attempted.

    • MapMatcher

      public MapMatcher(@NonNull SDKNativeEngine sdkEngine) throws InstantiationErrorException

      Creates a new instance of this class.

      Parameters:
      sdkEngine -

      A SDKEngine instance.

      Throws:
      InstantiationErrorException -

      Indicates what went wrong when the instantiation was attempted.

    • MapMatcher

      public MapMatcher(@NonNull SDKNativeEngine sdkEngine, boolean useRenderingLayers) throws InstantiationErrorException

      Creates a new instance of this class.

      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.

      Throws:
      InstantiationErrorException -

      Indicates what went wrong when the instantiation was attempted.

  • Method Details

    • match

      @Nullable public MapMatchedLocation match(@NonNull Location location)

      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, null 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, null 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.

      Parameters:
      location -

      The input location.

      Returns:

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