LocationManager  |  API reference  |  Android Developers (original) (raw)

public class LocationManager
extends [Object](/reference/java/lang/Object) ``

This class provides access to the system location services. These services allow applications to obtain periodic updates of the device's geographical location, or to be notified when the device enters the proximity of a given geographical location.

Unless otherwise noted, all Location API methods require the[Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or[Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION) permissions. If your application only has the coarse permission then providers will still return location results, but the exact location will be obfuscated to a coarse level of accuracy.
Requires the [PackageManager#FEATURE_LOCATION](/reference/android/content/pm/PackageManager#FEATURE%5FLOCATION) feature which can be detected using [PackageManager.hasSystemFeature(String)](/reference/android/content/pm/PackageManager#hasSystemFeature%28java.lang.String%29).

Summary

Constants
String ACTION_GNSS_CAPABILITIES_CHANGED Broadcast intent action when GNSS capabilities change.
String EXTRA_GNSS_CAPABILITIES Intent extra included with ACTION_GNSS_CAPABILITIES_CHANGED broadcasts, containing the new GnssCapabilities.
String EXTRA_LOCATION_ENABLED Intent extra included with MODE_CHANGED_ACTION broadcasts, containing the boolean enabled state of location.
String EXTRA_PROVIDER_ENABLED Intent extra included with PROVIDERS_CHANGED_ACTION broadcasts, containing the boolean enabled state of the location provider that has changed.
String EXTRA_PROVIDER_NAME Intent extra included with PROVIDERS_CHANGED_ACTION broadcasts, containing the name of the location provider that has changed.
String FUSED_PROVIDER Standard name of the fused location provider.
String GPS_PROVIDER Standard name of the GNSS location provider.
String KEY_FLUSH_COMPLETE Key used for an extra holding an integer request code when location flush completion is sent using a PendingIntent.
String KEY_LOCATIONS Key used for an extra holding a array of Locations when a location change is sent using a PendingIntent.
String KEY_LOCATION_CHANGED Key used for an extra holding a Location value when a location change is sent using a PendingIntent.
String KEY_PROVIDER_ENABLED Key used for an extra holding a boolean enabled/disabled status value when a provider enabled/disabled event is broadcast using a PendingIntent.
String KEY_PROXIMITY_ENTERING Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false)..
String KEY_STATUS_CHANGED This constant was deprecated in API level 29. Status changes are deprecated and no longer broadcast from Android Q onwards.
String MODE_CHANGED_ACTION Broadcast intent action when the device location enabled state changes.
String NETWORK_PROVIDER Standard name of the network location provider.
String PASSIVE_PROVIDER A special location provider for receiving locations without actively initiating a location fix.
String PROVIDERS_CHANGED_ACTION Broadcast intent action when the set of enabled location providers changes.
Public methods
boolean addGpsStatusListener(GpsStatus.Listener listener) This method was deprecated in API level 24. Use registerGnssStatusCallback(GnssStatus.Callback,Handler) or registerGnssStatusCallback(Executor,GnssStatus.Callback) instead.
boolean addNmeaListener(OnNmeaMessageListener listener, Handler handler) Adds an NMEA listener.
boolean addNmeaListener(OnNmeaMessageListener listener) This method was deprecated in API level 30. Use addNmeaListener(OnNmeaMessageListener,Handler) or addNmeaListener(Executor,OnNmeaMessageListener) instead.
boolean addNmeaListener(GpsStatus.NmeaListener listener) This method was deprecated in API level 24. Use addNmeaListener(OnNmeaMessageListener,Handler) or addNmeaListener(Executor,OnNmeaMessageListener) instead.
boolean addNmeaListener(Executor executor, OnNmeaMessageListener listener) Adds an NMEA listener.
void addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent pendingIntent) Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius.
void addTestProvider(String provider, ProviderProperties properties) Creates a test location provider and adds it to the set of active providers.
void addTestProvider(String provider, ProviderProperties properties, Set<String> extraAttributionTags) Creates a test location provider and adds it to the set of active providers.
void addTestProvider(String provider, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerUsage, int accuracy) Creates a test location provider and adds it to the set of active providers.
void clearTestProviderEnabled(String provider) This method was deprecated in API level 29. Use setTestProviderEnabled(String,boolean) instead.
void clearTestProviderLocation(String provider) This method was deprecated in API level 29. This method has always been a no-op, and may be removed in the future.
void clearTestProviderStatus(String provider) This method was deprecated in API level 29. This method has no effect.
List<String> getAllProviders() Returns a list of the names of all available location providers.
String getBestProvider(Criteria criteria, boolean enabledOnly) This method was deprecated in API level 34. Criteria based APIs are deprecated, prefer to select a provider explicitly.
void getCurrentLocation(String provider, LocationRequest locationRequest, CancellationSignal cancellationSignal, Executor executor, Consumer<Location> consumer) Asynchronously returns a single current location fix from the given provider based on the given LocationRequest.
void getCurrentLocation(String provider, CancellationSignal cancellationSignal, Executor executor, Consumer<Location> consumer) Asynchronously returns a single current location fix from the given provider.
List<GnssAntennaInfo> getGnssAntennaInfos() Returns the current list of GNSS antenna infos, or null if unknown or unsupported.
GnssCapabilities getGnssCapabilities() Returns the supported capabilities of the GNSS chipset.
String getGnssHardwareModelName() Returns the model name (including vendor and hardware/software version) of the GNSS hardware driver, or null if this information is not available.
int getGnssYearOfHardware() Returns the model year of the GNSS hardware and software build, or 0 if the model year is before 2016.
GpsStatus getGpsStatus(GpsStatus status) This method was deprecated in API level 24. GpsStatus APIs are deprecated, use GnssStatus APIs instead. No longer supported in apps targeting S and above.
Location getLastKnownLocation(String provider) Gets the last known location from the given provider, or null if there is no last known location.
LocationProvider getProvider(String provider) This method was deprecated in API level 31. This method has no way to indicate that a provider's properties are unknown, and so may return incorrect results on rare occasions. Use getProviderProperties(String) instead.
ProviderProperties getProviderProperties(String provider) Returns the properties of the given provider, or null if the properties are currently unknown.
List<String> getProviders(boolean enabledOnly) Returns a list of the names of available location providers.
List<String> getProviders(Criteria criteria, boolean enabledOnly) This method was deprecated in API level 34. Criteria based APIs are deprecated, prefer to select a provider explicitly.
boolean hasProvider(String provider) Returns true if the given location provider exists on this device, irrespective of whether it is currently enabled or not.
boolean isLocationEnabled() Returns the current enabled/disabled state of location.
boolean isProviderEnabled(String provider) Returns the current enabled/disabled status of the given provider.
boolean registerAntennaInfoListener(Executor executor, GnssAntennaInfo.Listener listener) Registers a GNSS antenna info listener that will receive all changes to antenna info.
boolean registerGnssMeasurementsCallback(Executor executor, GnssMeasurementsEvent.Callback callback) Registers a GNSS measurements callback.
boolean registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback) This method was deprecated in API level 30. Use registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback,Handler) or registerGnssMeasurementsCallback(Executor,GnssMeasurementsEvent.Callback) instead.
boolean registerGnssMeasurementsCallback(GnssMeasurementRequest request, Executor executor, GnssMeasurementsEvent.Callback callback) Registers a GNSS measurement callback.
boolean registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback, Handler handler) Registers a GNSS measurements callback.
boolean registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback, Handler handler) Registers a GNSS navigation message callback.
boolean registerGnssNavigationMessageCallback(Executor executor, GnssNavigationMessage.Callback callback) Registers a GNSS navigation message callback.
boolean registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback) This method was deprecated in API level 30. Use registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback,Handler) or registerGnssNavigationMessageCallback(Executor,GnssNavigationMessage.Callback) instead.
boolean registerGnssStatusCallback(GnssStatus.Callback callback) This method was deprecated in API level 30. Use registerGnssStatusCallback(GnssStatus.Callback,Handler) or registerGnssStatusCallback(Executor,GnssStatus.Callback) instead.
boolean registerGnssStatusCallback(GnssStatus.Callback callback, Handler handler) Registers a GNSS status callback.
boolean registerGnssStatusCallback(Executor executor, GnssStatus.Callback callback) Registers a GNSS status callback.
void removeGpsStatusListener(GpsStatus.Listener listener) This method was deprecated in API level 24. use unregisterGnssStatusCallback(GnssStatus.Callback) instead. No longer supported in apps targeting S and above.
void removeNmeaListener(OnNmeaMessageListener listener) Removes an NMEA listener.
void removeNmeaListener(GpsStatus.NmeaListener listener) This method was deprecated in API level 24. Use removeNmeaListener(OnNmeaMessageListener) instead.
void removeProximityAlert(PendingIntent intent) Removes the proximity alert with the given PendingIntent.
void removeTestProvider(String provider) Removes the test location provider with the given name or does nothing if no such test location provider exists.
void removeUpdates(LocationListener listener) Removes all location updates for the specified LocationListener.
void removeUpdates(PendingIntent pendingIntent) Removes location updates for the specified PendingIntent.
void requestFlush(String provider, LocationListener listener, int requestCode) Requests that the given provider flush any batched locations to listeners.
void requestFlush(String provider, PendingIntent pendingIntent, int requestCode) Requests that the given provider flush any batched locations to listeners.
void requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, LocationListener listener) Register for location updates from the given provider with the given arguments, and a callback on the Looper of the calling thread.
void requestLocationUpdates(long minTimeMs, float minDistanceM, Criteria criteria, LocationListener listener, Looper looper) This method was deprecated in API level 31. UserequestLocationUpdates(String,long,float,LocationListener,Looper) instead to explicitly select a provider.
void requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, LocationListener listener, Looper looper) Register for location updates from the given provider with the given arguments, and a callback on the specified Looper.
void requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, Executor executor, LocationListener listener) Register for location updates using the named provider, and a callback on the specified Executor.
void requestLocationUpdates(String provider, LocationRequest locationRequest, PendingIntent pendingIntent) Register for location updates from the specified provider, using a LocationRequest, and callbacks delivered via the provided PendingIntent.
void requestLocationUpdates(String provider, LocationRequest locationRequest, Executor executor, LocationListener listener) Register for location updates from the specified provider, using a LocationRequest, and a callback on the specified Executor.
void requestLocationUpdates(long minTimeMs, float minDistanceM, Criteria criteria, PendingIntent pendingIntent) This method was deprecated in API level 31. Use requestLocationUpdates(String,long,float,PendingIntent) instead to explicitly select a provider.
void requestLocationUpdates(long minTimeMs, float minDistanceM, Criteria criteria, Executor executor, LocationListener listener) This method was deprecated in API level 31. UserequestLocationUpdates(String,long,float,Executor,LocationListener) instead to explicitly select a provider.
void requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, PendingIntent pendingIntent) Register for location updates using the named provider, and callbacks delivered via the provided PendingIntent.
void requestSingleUpdate(String provider, PendingIntent pendingIntent) This method was deprecated in API level 30. Use getCurrentLocation(String,CancellationSignal,Executor,Consumer) instead as it does not carry a risk of extreme battery drain.
void requestSingleUpdate(Criteria criteria, PendingIntent pendingIntent) This method was deprecated in API level 30. Use getCurrentLocation(String,CancellationSignal,Executor,Consumer) instead as it does not carry a risk of extreme battery drain.
void requestSingleUpdate(String provider, LocationListener listener, Looper looper) This method was deprecated in API level 30. Use getCurrentLocation(String,CancellationSignal,Executor,Consumer) instead as it does not carry a risk of extreme battery drain.
void requestSingleUpdate(Criteria criteria, LocationListener listener, Looper looper) This method was deprecated in API level 30. Use getCurrentLocation(String,CancellationSignal,Executor,Consumer) instead as it does not carry a risk of extreme battery drain.
boolean sendExtraCommand(String provider, String command, Bundle extras) Sends additional commands to a location provider.
void setTestProviderEnabled(String provider, boolean enabled) Sets the given test provider to be enabled or disabled.
void setTestProviderLocation(String provider, Location location) Sets a new location for the given test provider.
void setTestProviderStatus(String provider, int status, Bundle extras, long updateTime) This method was deprecated in API level 29. This method has no effect.
void unregisterAntennaInfoListener(GnssAntennaInfo.Listener listener) Unregisters a GNSS antenna info listener.
void unregisterGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback) Unregisters a GPS Measurement callback.
void unregisterGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback) Unregisters a GNSS Navigation Message callback.
void unregisterGnssStatusCallback(GnssStatus.Callback callback) Removes a GNSS status callback.
Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

ACTION_GNSS_CAPABILITIES_CHANGED

public static final String ACTION_GNSS_CAPABILITIES_CHANGED

Broadcast intent action when GNSS capabilities change. This is most common at boot time as GNSS capabilities are queried from the chipset. Includes an intent extra,[EXTRA_GNSS_CAPABILITIES](/reference/android/location/LocationManager#EXTRA%5FGNSS%5FCAPABILITIES), with the new [GnssCapabilities](/reference/android/location/GnssCapabilities).

Constant Value: "android.location.action.GNSS_CAPABILITIES_CHANGED"

public static final String EXTRA_LOCATION_ENABLED

Intent extra included with [MODE_CHANGED_ACTION](/reference/android/location/LocationManager#MODE%5FCHANGED%5FACTION) broadcasts, containing the boolean enabled state of location.

Constant Value: "android.location.extra.LOCATION_ENABLED"

public static final String EXTRA_PROVIDER_ENABLED

Intent extra included with [PROVIDERS_CHANGED_ACTION](/reference/android/location/LocationManager#PROVIDERS%5FCHANGED%5FACTION) broadcasts, containing the boolean enabled state of the location provider that has changed.

Constant Value: "android.location.extra.PROVIDER_ENABLED"

public static final String EXTRA_PROVIDER_NAME

Intent extra included with [PROVIDERS_CHANGED_ACTION](/reference/android/location/LocationManager#PROVIDERS%5FCHANGED%5FACTION) broadcasts, containing the name of the location provider that has changed.

Constant Value: "android.location.extra.PROVIDER_NAME"

FUSED_PROVIDER

public static final String FUSED_PROVIDER

Standard name of the fused location provider.

If present, this provider may combine inputs from several other location providers to provide the best possible location fix. It is implicitly used for all requestLocationUpdates APIs that involve a [Criteria](/reference/android/location/Criteria).

Constant Value: "fused"

GPS_PROVIDER

public static final String GPS_PROVIDER

Standard name of the GNSS location provider.

If present, this provider determines location using GNSS satellites. The responsiveness and accuracy of location fixes may depend on GNSS signal conditions.

Locations returned from this provider are with respect to the primary GNSS antenna position within the device. [getGnssAntennaInfos()](/reference/android/location/LocationManager#getGnssAntennaInfos%28%29) may be used to determine the GNSS antenna position with respect to the Android Coordinate System, and convert between them if necessary. This is generally only necessary for high accuracy applications.

The extras Bundle for locations derived by this location provider may contain the following key/value pairs:

Constant Value: "gps"

KEY_FLUSH_COMPLETE

public static final String KEY_FLUSH_COMPLETE

Key used for an extra holding an integer request code when location flush completion is sent using a PendingIntent.

Constant Value: "flushComplete"

KEY_LOCATIONS

public static final String KEY_LOCATIONS

Key used for an extra holding a array of [Location](/reference/android/location/Location)s when a location change is sent using a PendingIntent. This key will only be present if the location change includes multiple (ie, batched) locations, otherwise only [KEY_LOCATION_CHANGED](/reference/android/location/LocationManager#KEY%5FLOCATION%5FCHANGED) will be present. Use [Intent.getParcelableArrayExtra(String)](/reference/android/content/Intent#getParcelableArrayExtra%28java.lang.String%29) to retrieve the locations.

The array of locations will never be empty, and will ordered from earliest location to latest location, the same as with [LocationListener.onLocationChanged(List)](/reference/android/location/LocationListener#onLocationChanged%28java.util.List<android.location.Location>%29).

Constant Value: "locations"

KEY_LOCATION_CHANGED

public static final String KEY_LOCATION_CHANGED

Key used for an extra holding a [Location](/reference/android/location/Location) value when a location change is sent using a PendingIntent. If the location change includes a list of batched locations via[KEY_LOCATIONS](/reference/android/location/LocationManager#KEY%5FLOCATIONS) then this key will still be present, and will hold the last location in the batch. Use [Intent.getParcelableExtra(String)](/reference/android/content/Intent#getParcelableExtra%28java.lang.String%29) to retrieve the location.

Constant Value: "location"

KEY_PROVIDER_ENABLED

public static final String KEY_PROVIDER_ENABLED

Key used for an extra holding a boolean enabled/disabled status value when a provider enabled/disabled event is broadcast using a PendingIntent.

Constant Value: "providerEnabled"

KEY_PROXIMITY_ENTERING

public static final String KEY_PROXIMITY_ENTERING

Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false)..

Constant Value: "entering"

KEY_STATUS_CHANGED

public static final String KEY_STATUS_CHANGED

This constant was deprecated in API level 29.
Status changes are deprecated and no longer broadcast from Android Q onwards.

This key is no longer in use.

Key used for a Bundle extra holding an Integer status value when a status change is broadcast using a PendingIntent.

Constant Value: "status"

MODE_CHANGED_ACTION

public static final String MODE_CHANGED_ACTION

Broadcast intent action when the device location enabled state changes. From Android R and above, will include a boolean intent extra, [EXTRA_LOCATION_ENABLED](/reference/android/location/LocationManager#EXTRA%5FLOCATION%5FENABLED), with the enabled state of location.

Constant Value: "android.location.MODE_CHANGED"

NETWORK_PROVIDER

public static final String NETWORK_PROVIDER

Standard name of the network location provider.

If present, this provider determines location based on nearby of cell tower and WiFi access points. Operation of this provider may require a data connection.

Constant Value: "network"

PASSIVE_PROVIDER

public static final String PASSIVE_PROVIDER

A special location provider for receiving locations without actively initiating a location fix. This location provider is always present.

This provider can be used to passively receive location updates when other applications or services request them without actually requesting the locations yourself. This provider will only return locations generated by other providers.

Constant Value: "passive"

PROVIDERS_CHANGED_ACTION

public static final String PROVIDERS_CHANGED_ACTION

Broadcast intent action when the set of enabled location providers changes. To check the status of a provider, use [isProviderEnabled(String)](/reference/android/location/LocationManager#isProviderEnabled%28java.lang.String%29). From Android Q and above, will include a string intent extra, [EXTRA_PROVIDER_NAME](/reference/android/location/LocationManager#EXTRA%5FPROVIDER%5FNAME), with the name of the provider whose state has changed. From Android R and above, will include a boolean intent extra,[EXTRA_PROVIDER_ENABLED](/reference/android/location/LocationManager#EXTRA%5FPROVIDER%5FENABLED), with the enabled state of the provider.

Constant Value: "android.location.PROVIDERS_CHANGED"

Public methods

addNmeaListener

public boolean addNmeaListener (Executor executor, OnNmeaMessageListener listener)

Adds an NMEA listener. GNSS NMEA information will only be received while the[GPS_PROVIDER](/reference/android/location/LocationManager#GPS%5FPROVIDER) is enabled, and while the client app is in the foreground.
Requires [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
executor Executor: the executor that the listener runs on. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener OnNmeaMessageListener: the listener to register. This value cannot be null.
Returns
boolean true always
Throws
IllegalArgumentException if executor is null
IllegalArgumentException if listener is null
SecurityException if the ACCESS_FINE_LOCATION permission is not present

addProximityAlert

public void addProximityAlert (double latitude, double longitude, float radius, long expiration, PendingIntent pendingIntent)

Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius.

When the device detects that it has entered or exited the area surrounding the location, the given PendingIntent will be fired.

The fired intent will have a boolean extra added with key [KEY_PROXIMITY_ENTERING](/reference/android/location/LocationManager#KEY%5FPROXIMITY%5FENTERING). If the value is true, the device is entering the proximity region; if false, it is exiting.

Due to the approximate nature of position estimation, if the device passes through the given area briefly, it is possible that no Intent will be fired. Similarly, an intent could be fired if the device passes very close to the given area but does not actually enter it.

Before API version 17, this method could be used with[Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION) or[Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION). From API version 17 and onwards, this method requires [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION) permission.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
latitude double: the latitude of the central point of the alert region
longitude double: the longitude of the central point of the alert region
radius float: the radius of the central point of the alert region in meters
expiration long: expiration realtime for this proximity alert in milliseconds, or -1 to indicate no expiration
pendingIntent PendingIntent: a PendingIntent that will sent when entry to or exit from the alert region is detected. This value cannot be null.
Throws
SecurityException if Manifest.permission.ACCESS_FINE_LOCATION permission is not present

addTestProvider

public void addTestProvider (String provider, ProviderProperties properties, Set<String> extraAttributionTags)

Creates a test location provider and adds it to the set of active providers. This provider will replace any provider with the same name that exists prior to this call.

Parameters
provider String: the provider name. This value cannot be null.
properties ProviderProperties: the provider properties. This value cannot be null.
extraAttributionTags Set: additional attribution tags associated with this provider. This value cannot be null.
Throws
IllegalArgumentException if provider is null
IllegalArgumentException if properties is null
SecurityException if mock location app op is not set to allowed for your app.

clearTestProviderLocation

public void clearTestProviderLocation (String provider)

This method was deprecated in API level 29.
This method has always been a no-op, and may be removed in the future.

Does nothing.

Parameters
provider String: This value cannot be null.

clearTestProviderStatus

public void clearTestProviderStatus (String provider)

This method was deprecated in API level 29.
This method has no effect.

This method has no effect as provider status has been deprecated and is no longer supported.

Parameters
provider String: This value cannot be null.

getAllProviders

public List<String> getAllProviders ()

Returns a list of the names of all available location providers. All providers are returned, including those that are currently disabled.

Returns
List<String> list of provider names. This value cannot be null.

getBestProvider

public String getBestProvider (Criteria criteria, boolean enabledOnly)

This method was deprecated in API level 34.
Criteria based APIs are deprecated, prefer to select a provider explicitly.

Returns the name of the provider that best meets the given criteria. Only providers that are permitted to be accessed by the caller will be returned. If several providers meet the criteria, the one with the best accuracy is returned. If no provider meets the criteria, the criteria are loosened in the following order:

Note that the requirement on monetary cost is not removed in this process.

Parameters
criteria Criteria: the criteria that need to be matched. This value cannot be null.
enabledOnly boolean: if true then only enabled providers are included
Returns
String name of the provider that best matches the criteria, or null if none match
Throws
IllegalArgumentException if criteria is null

getCurrentLocation

public void getCurrentLocation (String provider, LocationRequest locationRequest, CancellationSignal cancellationSignal, Executor executor, Consumer<Location> consumer)

Asynchronously returns a single current location fix from the given provider based on the given [LocationRequest](/reference/android/location/LocationRequest). This may activate sensors in order to compute a new location, unlike [getLastKnownLocation(String)](/reference/android/location/LocationManager#getLastKnownLocation%28java.lang.String%29), which will only return a cached fix if available. The given callback will be invoked once and only once, either with a valid location or with a null location if the provider was unable to generate a valid location.

A client may supply an optional [CancellationSignal](/reference/android/os/CancellationSignal). If this is used to cancel the operation, no callback should be expected after the cancellation.

This method may return locations from the very recent past (on the order of several seconds), but will never return older locations (for example, several minutes old or older). Clients may rely upon the guarantee that if this method returns a location, it will represent the best estimation of the location of the device in the present moment.

Clients calling this method from the background may notice that the method fails to determine a valid location fix more often than while in the foreground. Background applications may be throttled in their location accesses to some degree. The given location request may be used to provide hints on how a fresh location is computed if necessary. In particular [LocationRequest.getDurationMillis()](/reference/android/location/LocationRequest#getDurationMillis%28%29) can be used to provide maximum duration allowed before failing. The system will always cap the maximum amount of time a request for current location may run to some reasonable value (less than a minute for example) before the request is failed.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
locationRequest LocationRequest: the location request containing location parameters. This value cannot be null.
cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call. This value may be null.
executor Executor: the callback will take place on this Executor This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
consumer Consumer: the callback invoked with either a Location or null
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if executor is null
IllegalArgumentException if consumer is null
SecurityException if no suitable permission is present

getCurrentLocation

public void getCurrentLocation (String provider, CancellationSignal cancellationSignal, Executor executor, Consumer<Location> consumer)

Asynchronously returns a single current location fix from the given provider.

See[getCurrentLocation(String,LocationRequest,CancellationSignal,Executor,Consumer)](/reference/android/location/LocationManager#getCurrentLocation%28java.lang.String,%20android.location.LocationRequest,%20android.os.CancellationSignal,%20java.util.concurrent.Executor,%20java.util.function.Consumer<android.location.Location>%29) for more information.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call. This value may be null.
executor Executor: the callback will take place on this Executor This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
consumer Consumer: the callback invoked with either a Location or null
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if executor is null
IllegalArgumentException if consumer is null
SecurityException if no suitable permission is present

getGnssCapabilities

public GnssCapabilities getGnssCapabilities ()

Returns the supported capabilities of the GNSS chipset.

Returns
GnssCapabilities This value cannot be null.

getGnssHardwareModelName

public String getGnssHardwareModelName ()

Returns the model name (including vendor and hardware/software version) of the GNSS hardware driver, or null if this information is not available.

No device-specific serial number or ID is returned from this API.

Returns
String

getGnssYearOfHardware

public int getGnssYearOfHardware ()

Returns the model year of the GNSS hardware and software build, or 0 if the model year is before 2016.

Returns
int

getGpsStatus

public GpsStatus getGpsStatus (GpsStatus status)

This method was deprecated in API level 24.
GpsStatus APIs are deprecated, use [GnssStatus](/reference/android/location/GnssStatus) APIs instead. No longer supported in apps targeting S and above.

Retrieves information about the current status of the GPS engine. This should only be called from within the [GpsStatus.Listener.onGpsStatusChanged](/reference/android/location/GpsStatus.Listener#onGpsStatusChanged%28int%29) callback to ensure that the data is copied atomically. The caller may either pass in an existing [GpsStatus](/reference/android/location/GpsStatus) object to be overwritten, or pass null to create a new [GpsStatus](/reference/android/location/GpsStatus) object.
Requires [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
status GpsStatus: object containing GPS status details, or null.
Returns
GpsStatus status object containing updated GPS status.

getProvider

public LocationProvider getProvider (String provider)

This method was deprecated in API level 31.
This method has no way to indicate that a provider's properties are unknown, and so may return incorrect results on rare occasions. Use [getProviderProperties(String)](/reference/android/location/LocationManager#getProviderProperties%28java.lang.String%29) instead.

Returns the information about the location provider with the given name, or null if no provider exists by that name.

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
Returns
LocationProvider location provider information, or null if provider does not exist
Throws
IllegalArgumentException if provider is null

getProviderProperties

public ProviderProperties getProviderProperties (String provider)

Returns the properties of the given provider, or null if the properties are currently unknown. Provider properties may change over time, although this is discouraged, and should be rare. The most common transition is when provider properties go from being unknown to known, which is most common near boot time.

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
Returns
ProviderProperties location provider properties, or null if properties are currently unknown
Throws
IllegalArgumentException if provider is null or does not exist

getProviders

public List<String> getProviders (boolean enabledOnly)

Returns a list of the names of available location providers. If enabledOnly is false, this is functionally the same as [getAllProviders()](/reference/android/location/LocationManager#getAllProviders%28%29).

Parameters
enabledOnly boolean: if true then only enabled providers are included
Returns
List<String> list of provider names. This value cannot be null.

getProviders

public List<String> getProviders (Criteria criteria, boolean enabledOnly)

This method was deprecated in API level 34.
Criteria based APIs are deprecated, prefer to select a provider explicitly.

Returns a list of the names of available location providers that satisfy the given criteria.

Parameters
criteria Criteria: the criteria that providers must match. This value cannot be null.
enabledOnly boolean: if true then only enabled providers are included
Returns
List<String> list of provider names. This value cannot be null.
Throws
IllegalArgumentException if criteria is null

hasProvider

public boolean hasProvider (String provider)

Returns true if the given location provider exists on this device, irrespective of whether it is currently enabled or not.

Parameters
provider String: a potential location provider. This value cannot be null.
Returns
boolean true if the location provider exists, false otherwise
Throws
IllegalArgumentException if provider is null

isLocationEnabled

public boolean isLocationEnabled ()

Returns the current enabled/disabled state of location. To listen for changes, see[MODE_CHANGED_ACTION](/reference/android/location/LocationManager#MODE%5FCHANGED%5FACTION).

Returns
boolean true if location is enabled and false if location is disabled.

registerAntennaInfoListener

public boolean registerAntennaInfoListener (Executor executor, GnssAntennaInfo.Listener listener)

Registers a GNSS antenna info listener that will receive all changes to antenna info. Use[getGnssAntennaInfos()](/reference/android/location/LocationManager#getGnssAntennaInfos%28%29) to get current antenna info.

Not all GNSS chipsets support antenna info updates, see [getGnssCapabilities()](/reference/android/location/LocationManager#getGnssCapabilities%28%29). If unsupported, the listener will never be invoked.

Prior to Android S, this requires the [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION) permission.

Parameters
executor Executor: the executor that the listener runs on. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener GnssAntennaInfo.Listener: the listener to register. This value cannot be null.
Returns
boolean true always
Throws
IllegalArgumentException if executor is null
IllegalArgumentException if listener is null

registerGnssMeasurementsCallback

public boolean registerGnssMeasurementsCallback (Executor executor, GnssMeasurementsEvent.Callback callback)

Registers a GNSS measurements callback. GNSS measurements information will only be received while the [GPS_PROVIDER](/reference/android/location/LocationManager#GPS%5FPROVIDER) is enabled, and while the client app is in the foreground.

Not all GNSS chipsets support measurements updates, see [getGnssCapabilities()](/reference/android/location/LocationManager#getGnssCapabilities%28%29).

On Android R devices that have not yet upgraded to Android R QPR1, using this API will cause unavoidable crashes in the client application when GNSS measurements are received. If a client needs to receive GNSS measurements on Android R devices that have not been upgraded to QPR1, clients are instead encouraged to useLocationManagerCompat.registerGnssMeasurementsCallback() from the compat libraries instead to avoid this crash.
Requires [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
executor Executor: the executor that the callback runs on. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback GnssMeasurementsEvent.Callback: the callback to register. This value cannot be null.
Returns
boolean true always
Throws
IllegalArgumentException if executor is null
IllegalArgumentException if callback is null
SecurityException if the ACCESS_FINE_LOCATION permission is not present

registerGnssNavigationMessageCallback

public boolean registerGnssNavigationMessageCallback (Executor executor, GnssNavigationMessage.Callback callback)

Registers a GNSS navigation message callback. GNSS navigation messages will only be received while the [GPS_PROVIDER](/reference/android/location/LocationManager#GPS%5FPROVIDER) is enabled, and while the client app is in the foreground.

Not all GNSS chipsets support navigation message updates, see[getGnssCapabilities()](/reference/android/location/LocationManager#getGnssCapabilities%28%29).
Requires [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
executor Executor: the executor that the callback runs on. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback GnssNavigationMessage.Callback: the callback to register. This value cannot be null.
Returns
boolean true always
Throws
IllegalArgumentException if executor is null
IllegalArgumentException if callback is null
SecurityException if the ACCESS_FINE_LOCATION permission is not present

registerGnssStatusCallback

public boolean registerGnssStatusCallback (Executor executor, GnssStatus.Callback callback)

Registers a GNSS status callback. GNSS status information will only be received while the[GPS_PROVIDER](/reference/android/location/LocationManager#GPS%5FPROVIDER) is enabled, and while the client app is in the foreground.
Requires [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
executor Executor: the executor that the callback runs on. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback GnssStatus.Callback: the callback to register. This value cannot be null.
Returns
boolean true always
Throws
IllegalArgumentException if executor is null
IllegalArgumentException if callback is null
SecurityException if the ACCESS_FINE_LOCATION permission is not present

removeGpsStatusListener

public void removeGpsStatusListener (GpsStatus.Listener listener)

This method was deprecated in API level 24.
use [unregisterGnssStatusCallback(GnssStatus.Callback)](/reference/android/location/LocationManager#unregisterGnssStatusCallback%28android.location.GnssStatus.Callback%29) instead. No longer supported in apps targeting S and above.

Removes a GPS status listener.

Parameters
listener GpsStatus.Listener: GPS status listener object to remove

removeNmeaListener

public void removeNmeaListener (OnNmeaMessageListener listener)

Removes an NMEA listener.

Parameters
listener OnNmeaMessageListener: a OnNmeaMessageListener object to remove. This value cannot be null.

removeTestProvider

public void removeTestProvider (String provider)

Removes the test location provider with the given name or does nothing if no such test location provider exists.

Parameters
provider String: the provider name. This value cannot be null.
Throws
IllegalArgumentException if provider is null
SecurityException if mock location app op is not set to allowed for your app.

removeUpdates

public void removeUpdates (PendingIntent pendingIntent)

Removes location updates for the specified [PendingIntent](/reference/android/app/PendingIntent). Following this call, the PendingIntent will no longer receive location updates.

See [removeUpdates(LocationListener)](/reference/android/location/LocationManager#removeUpdates%28android.location.LocationListener%29) for more detail on how this method works.

Parameters
pendingIntent PendingIntent: pending intent that no longer needs location updates. This value cannot be null.
Throws
IllegalArgumentException if pendingIntent is null

requestFlush

public void requestFlush (String provider, PendingIntent pendingIntent, int requestCode)

Requests that the given provider flush any batched locations to listeners. The given PendingIntent (registered with the provider) will be sent with [KEY_FLUSH_COMPLETE](/reference/android/location/LocationManager#KEY%5FFLUSH%5FCOMPLETE) present in the extra keys, and requestCode as the corresponding value.

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
pendingIntent PendingIntent: a pendingIntent registered under the provider. This value cannot be null.
requestCode int: an arbitrary integer that will be passed back as the extra value forKEY_FLUSH_COMPLETE
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if pending intent is null or is not registered under the provider

requestLocationUpdates

public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, LocationListener listener)

Register for location updates from the given provider with the given arguments, and a callback on the [Looper](/reference/android/os/Looper) of the calling thread.

See [requestLocationUpdates(String,LocationRequest,Executor,LocationListener)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20android.location.LocationRequest,%20java.util.concurrent.Executor,%20android.location.LocationListener%29) for more detail on how this method works.

Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. For Jellybean and onwards however, it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
minTimeMs long: minimum time interval between location updates in milliseconds
minDistanceM float: minimum distance between location updates in meters
listener LocationListener: the listener to receive location updates. This value cannot be null.
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if listener is null
RuntimeException if the calling thread has no Looper
SecurityException if no suitable permission is present

requestLocationUpdates

public void requestLocationUpdates (long minTimeMs, float minDistanceM, Criteria criteria, LocationListener listener, Looper looper)

This method was deprecated in API level 31.
Use[requestLocationUpdates(String,long,float,LocationListener,Looper)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20long,%20float,%20android.location.LocationListener,%20android.os.Looper%29) instead to explicitly select a provider.

Register for location updates using a provider selected through the given Criteria, and a callback on the specified [Looper](/reference/android/os/Looper).

Note: Since Android KitKat, Criteria requests will always result in using the[FUSED_PROVIDER](/reference/android/location/LocationManager#FUSED%5FPROVIDER).

See [requestLocationUpdates(String,LocationRequest,Executor,LocationListener)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20android.location.LocationRequest,%20java.util.concurrent.Executor,%20android.location.LocationListener%29) for more detail on how this method works.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
minTimeMs long: minimum time interval between location updates in milliseconds
minDistanceM float: minimum distance between location updates in meters
criteria Criteria: contains parameters to choose the appropriate provider for location updates. This value cannot be null.
listener LocationListener: the listener to receive location updates. This value cannot be null.
looper Looper: This value may be null.
Throws
IllegalArgumentException if criteria is null
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

requestLocationUpdates

public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, LocationListener listener, Looper looper)

Register for location updates from the given provider with the given arguments, and a callback on the specified [Looper](/reference/android/os/Looper).

See [requestLocationUpdates(String,LocationRequest,Executor,LocationListener)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20android.location.LocationRequest,%20java.util.concurrent.Executor,%20android.location.LocationListener%29) for more detail on how this method works.

Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. For Jellybean and onwards however, it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
minTimeMs long: minimum time interval between location updates in milliseconds
minDistanceM float: minimum distance between location updates in meters
listener LocationListener: the listener to receive location updates. This value cannot be null.
looper Looper: the looper handling listener callbacks, or null to use the looper of the calling thread
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

requestLocationUpdates

public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, Executor executor, LocationListener listener)

Register for location updates using the named provider, and a callback on the specified [Executor](/reference/java/util/concurrent/Executor).

See [requestLocationUpdates(String,LocationRequest,Executor,LocationListener)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20android.location.LocationRequest,%20java.util.concurrent.Executor,%20android.location.LocationListener%29) for more detail on how this method works.

Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. For Jellybean and onwards however, it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
minTimeMs long: minimum time interval between location updates in milliseconds
minDistanceM float: minimum distance between location updates in meters
executor Executor: the executor handling listener callbacks. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener LocationListener: the listener to receive location updates. This value cannot be null.
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if executor is null
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

requestLocationUpdates

public void requestLocationUpdates (String provider, LocationRequest locationRequest, Executor executor, LocationListener listener)

Register for location updates from the specified provider, using a [LocationRequest](/reference/android/location/LocationRequest), and a callback on the specified [Executor](/reference/java/util/concurrent/Executor).

Only one request can be registered for each unique listener/provider pair, so any subsequent requests with the same provider and listener will overwrite all associated arguments. The same listener may be used across multiple providers with different requests for each provider.

It may take some time to receive the first location update depending on the conditions the device finds itself in. In order to take advantage of cached locations, application may consider using [getLastKnownLocation(String)](/reference/android/location/LocationManager#getLastKnownLocation%28java.lang.String%29) or [getCurrentLocation(String,LocationRequest,CancellationSignal,Executor,Consumer)](/reference/android/location/LocationManager#getCurrentLocation%28java.lang.String,%20android.location.LocationRequest,%20android.os.CancellationSignal,%20java.util.concurrent.Executor,%20java.util.function.Consumer<android.location.Location>%29) instead.

See [LocationRequest](/reference/android/location/LocationRequest) documentation for an explanation of various request parameters and how they can affect the received locations.

If your application wants to passively observe location updates from all providers, then use the [PASSIVE_PROVIDER](/reference/android/location/LocationManager#PASSIVE%5FPROVIDER). This provider does not turn on or modify active location providers, so you do not need to be as careful about minimum time and minimum distance parameters. However, if your application performs heavy work on a location update (such as network activity) then you should set an explicit fastest interval on your location request in case another application enables a location provider with extremely fast updates.

In case the provider you have selected is disabled, location updates will cease, and a provider availability update will be sent. As soon as the provider is enabled again, another provider availability update will be sent and location updates will resume.

Locations returned from [GPS_PROVIDER](/reference/android/location/LocationManager#GPS%5FPROVIDER) are with respect to the primary GNSS antenna position within the device. [getGnssAntennaInfos()](/reference/android/location/LocationManager#getGnssAntennaInfos%28%29) may be used to determine the GNSS antenna position with respect to the Android Coordinate System, and convert between them if necessary. This is generally only necessary for high accuracy applications.

When location callbacks are invoked, the system will hold a wakelock on your application's behalf for some period of time, but not indefinitely. If your application requires a long running wakelock within the location callback, you should acquire it yourself.

Spamming location requests is a drain on system resources, and the system has preventative measures in place to ensure that this behavior will never result in more locations than could be achieved with a single location request with an equivalent interval that is left in place the whole time. As part of this amelioration, applications that target Android S and above may receive cached or historical locations through their listener. These locations will never be older than the interval of the location request.

To unregister for location updates, use [removeUpdates(LocationListener)](/reference/android/location/LocationManager#removeUpdates%28android.location.LocationListener%29).
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
locationRequest LocationRequest: the location request containing location parameters. This value cannot be null.
executor Executor: the executor handling listener callbacks. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener LocationListener: the listener to receive location updates. This value cannot be null.
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if locationRequest is null
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

requestLocationUpdates

public void requestLocationUpdates (long minTimeMs, float minDistanceM, Criteria criteria, PendingIntent pendingIntent)

This method was deprecated in API level 31.
Use [requestLocationUpdates(String,long,float,PendingIntent)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20long,%20float,%20android.app.PendingIntent%29) instead to explicitly select a provider.

Register for location updates using a provider selected through the given Criteria, and callbacks delivered via the provided [PendingIntent](/reference/android/app/PendingIntent).

Note: Since Android KitKat, Criteria requests will always result in using the[FUSED_PROVIDER](/reference/android/location/LocationManager#FUSED%5FPROVIDER).

See [requestLocationUpdates(String,long,float,PendingIntent)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20long,%20float,%20android.app.PendingIntent%29) for more detail on how this method works.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
minTimeMs long: minimum time interval between location updates in milliseconds
minDistanceM float: minimum distance between location updates in meters
criteria Criteria: contains parameters to choose the appropriate provider for location updates. This value cannot be null.
pendingIntent PendingIntent: the pending intent to send location updates. This value cannot be null.
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if pendingIntent is null
SecurityException if no suitable permission is present

requestLocationUpdates

public void requestLocationUpdates (long minTimeMs, float minDistanceM, Criteria criteria, Executor executor, LocationListener listener)

This method was deprecated in API level 31.
Use[requestLocationUpdates(String,long,float,Executor,LocationListener)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20long,%20float,%20java.util.concurrent.Executor,%20android.location.LocationListener%29) instead to explicitly select a provider.

Register for location updates using a provider selected through the given Criteria, and a callback on the specified [Executor](/reference/java/util/concurrent/Executor).

Note: Since Android KitKat, Criteria requests will always result in using the[FUSED_PROVIDER](/reference/android/location/LocationManager#FUSED%5FPROVIDER).

See [requestLocationUpdates(String,LocationRequest,Executor,LocationListener)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20android.location.LocationRequest,%20java.util.concurrent.Executor,%20android.location.LocationListener%29) for more detail on how this method works.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
minTimeMs long: minimum time interval between location updates in milliseconds
minDistanceM float: minimum distance between location updates in meters
criteria Criteria: contains parameters to choose the appropriate provider for location updates. This value cannot be null.
executor Executor: the executor handling listener callbacks. This value cannot be null. Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can useContext.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener LocationListener: the listener to receive location updates. This value cannot be null.
Throws
IllegalArgumentException if criteria is null
IllegalArgumentException if executor is null
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

requestSingleUpdate

public void requestSingleUpdate (String provider, LocationListener listener, Looper looper)

This method was deprecated in API level 30.
Use [getCurrentLocation(String,CancellationSignal,Executor,Consumer)](/reference/android/location/LocationManager#getCurrentLocation%28java.lang.String,%20android.os.CancellationSignal,%20java.util.concurrent.Executor,%20java.util.function.Consumer<android.location.Location>%29) instead as it does not carry a risk of extreme battery drain.

Register for a single location update using the named provider and a callback.

See [requestLocationUpdates(String,long,float,LocationListener,Looper)](/reference/android/location/LocationManager#requestLocationUpdates%28java.lang.String,%20long,%20float,%20android.location.LocationListener,%20android.os.Looper%29) for more detail on how to use this method.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
listener LocationListener: the listener to receive location updates. This value cannot be null.
looper Looper: the looper handling listener callbacks, or null to use the looper of the calling thread
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

requestSingleUpdate

public void requestSingleUpdate (Criteria criteria, LocationListener listener, Looper looper)

This method was deprecated in API level 30.
Use [getCurrentLocation(String,CancellationSignal,Executor,Consumer)](/reference/android/location/LocationManager#getCurrentLocation%28java.lang.String,%20android.os.CancellationSignal,%20java.util.concurrent.Executor,%20java.util.function.Consumer<android.location.Location>%29) instead as it does not carry a risk of extreme battery drain.

Register for a single location update using a Criteria and a callback.

Note: Since Android KitKat, Criteria requests will always result in using the[FUSED_PROVIDER](/reference/android/location/LocationManager#FUSED%5FPROVIDER).

See [requestLocationUpdates(long,float,Criteria,PendingIntent)](/reference/android/location/LocationManager#requestLocationUpdates%28long,%20float,%20android.location.Criteria,%20android.app.PendingIntent%29) for more detail on how to use this method.
Requires [Manifest.permission.ACCESS_COARSE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FCOARSE%5FLOCATION) or [Manifest.permission.ACCESS_FINE_LOCATION](/reference/android/Manifest.permission#ACCESS%5FFINE%5FLOCATION)

Parameters
criteria Criteria: contains parameters to choose the appropriate provider for location updates. This value cannot be null.
listener LocationListener: the listener to receive location updates. This value cannot be null.
looper Looper: the looper handling listener callbacks, or null to use the looper of the calling thread
Throws
IllegalArgumentException if criteria is null
IllegalArgumentException if listener is null
SecurityException if no suitable permission is present

sendExtraCommand

public boolean sendExtraCommand (String provider, String command, Bundle extras)

Sends additional commands to a location provider. Can be used to support provider specific extensions to the Location Manager API.

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
command String: name of the command to send to the provider. This value cannot be null.
extras Bundle: optional arguments for the command, or null
Returns
boolean true always, the return value may be ignored

setTestProviderEnabled

public void setTestProviderEnabled (String provider, boolean enabled)

Sets the given test provider to be enabled or disabled.

Parameters
provider String: the provider name. This value cannot be null.
enabled boolean: the mock enabled value
Throws
IllegalArgumentException if provider is null or not a test provider
SecurityException if mock location app op is not set to allowed for your app.

setTestProviderLocation

public void setTestProviderLocation (String provider, Location location)

Sets a new location for the given test provider. This location will be identiable as a mock location to all clients via [Location.isMock()](/reference/android/location/Location#isMock%28%29).

The location object must have a minimum number of fields set to be considered valid, as per documentation on [Location](/reference/android/location/Location) class.

Parameters
provider String: the provider name. This value cannot be null.
location Location: the mock location. This value cannot be null.
Throws
IllegalArgumentException if the provider is null or not a test provider
IllegalArgumentException if the location is null or incomplete
SecurityException if mock location app op is not set to allowed for your app.

setTestProviderStatus

public void setTestProviderStatus (String provider, int status, Bundle extras, long updateTime)

This method was deprecated in API level 29.
This method has no effect.

This method has no effect as provider status has been deprecated and is no longer supported.

Parameters
provider String: This value cannot be null.
status int
extras Bundle: This value may be null.
updateTime long

unregisterAntennaInfoListener

public void unregisterAntennaInfoListener (GnssAntennaInfo.Listener listener)

Unregisters a GNSS antenna info listener.

Parameters
listener GnssAntennaInfo.Listener: a GnssAntennaInfo.Listener object to remove. This value cannot be null.

unregisterGnssNavigationMessageCallback

public void unregisterGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)

Unregisters a GNSS Navigation Message callback.

Parameters
callback GnssNavigationMessage.Callback: a GnssNavigationMessage.Callback object to remove. This value cannot be null.

unregisterGnssStatusCallback

public void unregisterGnssStatusCallback (GnssStatus.Callback callback)

Removes a GNSS status callback.

Parameters
callback GnssStatus.Callback: GNSS status callback object to remove. This value cannot be null.