Built-in location engines

The Location module provides a LocationEngine interface to provide location updates to other modules of the Maps and Navigation SDKs. Those modules can subscribe to continue to receive location updates. You can also implement your own LocationEngine. See the instructions in the Custom Location Engine guide.

The Location module provides a predefined set of location engines:

  • AndroidLocationEngine – Based on the Android system location services.
  • SimulationLocationEngine - Simulates updates for testing purposes and previewing routes. Read more in the Simulation guide.
  • MapMatchedLocationEngine - publishes map matched locations generated by navigation. This is used in driving mode to snap the chevron shown on the map to the road network. It is described in detail in the Navigation module documentation.

Read how to set up a project and add these location engine dependencies in the Quickstart.

AndroidLocationEngine

The AndroidLocationEngine updates user locations using the Android system location services. Under the hood, it uses the LocationManager class to request location updates.

The location engine requires Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION permissions. If your application only has coarse permission then providers will still return location results, but the exact location will be obfuscated to a coarse level of accuracy.

To create the AndroidLocationEngine object you need to provide the context. Optionally, it can be configured by passing an AndroidLocationEngineConfig object as a second parameter.

Using the AndroidLocationEngineConfig you can set the minimum time interval between location updates in milliseconds, and the minimum distance between location updates in meters. Both values are set to 0 by default, meaning that location updates are provided as often as possible.

1val androidLocationEngineConfig = AndroidLocationEngineConfig(
2 minTimeInterval = Duration.ofMilliseconds(250L),
3 minDistance = Distance.ofMeters(20.0)
4)
5val locationEngine: LocationEngine = AndroidLocationEngine(
6 context = applicationContext,
7 config = androidLocationEngineConfig
8)

The following steps explain how to use the initialized LocationEngine to receive location updates.

  1. Set the location engine to either the map or navigation.
    tomTomMap.setLocationEngine(locationEngine)
  2. Enable the engine to receive location updates.
    locationEngine.enable()
  3. At any time the LocationEngine can be disabled to stop receiving location updates. If the engine will not be used anymore, dispose of its resources.
    locationEngine.disable()
    locationEngine.dispose()
  4. Location updates can be observed using OnLocationUpdateListener. Set it to the LocationEngine instance. Remember to unregister set listeners if they are no longer needed.
    1val onLocationUpdateListener =
    2 OnLocationUpdateListener { location: GeoLocation -> /* YOUR CODE GOES HERE */ }
    3locationEngine.addOnLocationUpdateListener(onLocationUpdateListener)
    4locationEngine.removeOnLocationUpdateListener(onLocationUpdateListener)
  5. The LocationEngine has a property with the last known GeoLocation. If the location was not determined yet, it will not be returned.
    val lastLocation = locationEngine.lastKnownLocation