Built-in location provider

VERSION 1.0.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:

AndroidLocationProvider – 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.

AndroidLocationProvider

The AndroidLocationProvider 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 AndroidLocationProvider object you must provide the context. Optionally, it can be configured by passing an AndroidLocationProviderConfig object as a second parameter.

Using the AndroidLocationProviderConfig 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.

1val androidLocationProviderConfig = AndroidLocationProviderConfig(
2    minTimeInterval = 250L.milliseconds,
3    minDistance = Distance.meters(20.0)
4)
5val androidLocationProvider: LocationProvider = AndroidLocationProvider(
6    context = applicationContext,
7    config = androidLocationProviderConfig
8)

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 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)
```
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: