Developer

Built-in location provider

VERSION 1.20.0

The Location module provides a LocationProvider 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 LocationProvider. See the instructions in the Custom Location Provider guide.

The Location module provides a predefined set of location providers:

  • Default LocationProvider – Based on the Android system location services.
  • SimulationLocationProvider - Simulates updates for testing purposes and previewing routes. Read more in the Simulation guide.
  • MapMatchedLocationProvider - 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 Map-matched location provider.

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

Default LocationProvider

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

The location provider 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 default LocationProvider object you must provide the context to the DefaultLocationProviderFactory.create() method. Optionally, it can be configured by passing an LocationProviderConfig object as a second parameter.

Using the LocationProviderConfig you can set the minimum time interval between location updates in milliseconds, and the minimum distance between location updates in meters. By default, both values are set to 0. This means that location updates are provided as often as possible.

Additionally, you can specify CoroutineDispatcher to handle location updates on a dedicated thread. TomTom recommends using CoroutineDispatcher to prevent cases when handling location updates blocks the main thread.

Modifying UI elements from a location listener callback is restricted if you use a CoroutineDispatcher associated with the background thread.

1val locationProviderConfig =
2    LocationProviderConfig(
3        minTimeInterval = 250L.milliseconds,
4        minDistance = Distance.meters(20.0),
5    )
6val defaultLocationProvider: LocationProvider =
7    DefaultLocationProviderFactory.create(
8        context = applicationContext,
9        dispatcher = Dispatchers.Default,
10        config = locationProviderConfig,
11    )

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

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

Next steps

Since you have learned how to use the built-in location provider, here are recommendations for the next steps: