Built-in location provider
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 aCoroutineDispatcher
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.
- Set the location provider to either the map or navigation.
tomTomMap.setLocationProvider(locationProvider)
- Enable the engine to receive location updates.
locationProvider.enable()
- 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() - Location updates can be observed using
OnLocationUpdateListener
. Set it to theLocationProvider
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) - The
LocationProvider
has a property with the last knownGeoLocation
. 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: