Added in API level 1

Summary: Constants | Methods | Inherited Methods

LocationManager

public class LocationManager
extends Object

java.lang.Object
↳	android.location.LocationManager

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 fire an application-specified Intent when the device enters the proximity of a given geographical location.

Unless noted, all Location API methods require the Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION permissions. If your application only has the coarse permission then it will not have access to the GPS or passive location providers. Other providers will still return location results, but the update rate will be throttled and the exact location will be obfuscated to a coarse level of accuracy.
Requires the PackageManager#FEATURE_LOCATION feature which can be detected using PackageManager.hasSystemFeature(String).

Summary

Constants
`String`	`GPS_PROVIDER` Name of the GPS location provider.
`String`	`KEY_LOCATION_CHANGED` Key used for a Bundle extra holding a Location value when a location change is broadcast using a PendingIntent.
`String`	`KEY_PROVIDER_ENABLED` Key used for a Bundle extra holding an Boolean 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 Q. Status changes are deprecated and no longer broadcast.
`String`	`MODE_CHANGED_ACTION` Broadcast intent action when the device location mode changes.
`String`	`NETWORK_PROVIDER` Name of the network location provider.
`String`	`PASSIVE_PROVIDER` A special location provider for receiving locations without actually 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(android.location.GnssStatus.Callback)` instead.
`boolean`	`addNmeaListener(OnNmeaMessageListener listener, Handler handler)` Adds an NMEA listener.
`boolean`	`addNmeaListener(OnNmeaMessageListener listener)` Adds an NMEA listener.
`boolean`	`addNmeaListener(GpsStatus.NmeaListener listener)` This method was deprecated in API level 24. use `addNmeaListener(android.location.OnNmeaMessageListener)` instead.
`void`	`addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent)` Set a proximity alert for the location given by the position (latitude, longitude) and the given radius.
`void`	`addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy)` Creates a mock location provider and adds it to the set of active providers.
`void`	`clearTestProviderEnabled(String provider)` This method was deprecated in API level Q. Use `setTestProviderEnabled(java.lang.String, boolean)` instead.
`void`	`clearTestProviderLocation(String provider)` This method was deprecated in API level Q. This function has always been a no-op, and may be removed in the future.
`void`	`clearTestProviderStatus(String provider)` This method was deprecated in API level Q. This method has no effect.
`List<String>`	`getAllProviders()` Returns a list of the names of all known location providers.
`String`	`getBestProvider(Criteria criteria, boolean enabledOnly)` Returns the name of the provider that best meets the given criteria.
`String`	`getGnssHardwareModelName()` Returns the Model Name (including Vendor and Hardware/Software Version) of the GNSS hardware driver.
`int`	`getGnssYearOfHardware()` Returns the model year of the GNSS hardware and software build.
`GpsStatus`	`getGpsStatus(GpsStatus status)` Retrieves information about the current status of the GPS engine.
`Location`	`getLastKnownLocation(String provider)` Returns a Location indicating the data from the last known location fix obtained from the given provider.
`LocationProvider`	`getProvider(String name)` Returns the information associated with the location provider of the given name, or null if no provider exists by that name.
`List<String>`	`getProviders(boolean enabledOnly)` Returns a list of the names of location providers.
`List<String>`	`getProviders(Criteria criteria, boolean enabledOnly)` Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do.
`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`	`registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)` Registers a GPS Measurement callback.
`boolean`	`registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback, Handler handler)` Registers a GPS Measurement callback.
`boolean`	`registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback, Handler handler)` Registers a GNSS Navigation Message callback.
`boolean`	`registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)` Registers a GNSS Navigation Message callback.
`boolean`	`registerGnssStatusCallback(GnssStatus.Callback callback)` Registers a GNSS status callback.
`boolean`	`registerGnssStatusCallback(GnssStatus.Callback callback, Handler handler)` Registers a GNSS status callback.
`void`	`removeGpsStatusListener(GpsStatus.Listener listener)` This method was deprecated in API level 24. use `unregisterGnssStatusCallback(android.location.GnssStatus.Callback)` instead.
`void`	`removeNmeaListener(OnNmeaMessageListener listener)` Removes an NMEA listener.
`void`	`removeNmeaListener(GpsStatus.NmeaListener listener)` This method was deprecated in API level 24. use `removeNmeaListener(android.location.OnNmeaMessageListener)` instead.
`void`	`removeProximityAlert(PendingIntent intent)` Removes the proximity alert with the given PendingIntent.
`void`	`removeTestProvider(String provider)` Removes the mock location provider with the given name.
`void`	`removeUpdates(LocationListener listener)` Removes all location updates for the specified LocationListener.
`void`	`removeUpdates(PendingIntent intent)` Removes all location updates for the specified pending intent.
`void`	`requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener)` Register for location updates using the named provider, and a pending intent.
`void`	`requestLocationUpdates(long minTime, float minDistance, Criteria criteria, LocationListener listener, Looper looper)` Register for location updates using a Criteria, and a callback on the specified looper thread.
`void`	`requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener, Looper looper)` Register for location updates using the named provider, and a callback on the specified looper thread.
`void`	`requestLocationUpdates(long minTime, float minDistance, Criteria criteria, PendingIntent intent)` Register for location updates using a Criteria and pending intent.
`void`	`requestLocationUpdates(String provider, long minTime, float minDistance, PendingIntent intent)` Register for location updates using the named provider, and a pending intent.
`void`	`requestSingleUpdate(String provider, PendingIntent intent)` Register for a single location update using a named provider and pending intent.
`void`	`requestSingleUpdate(Criteria criteria, PendingIntent intent)` Register for a single location update using a Criteria and pending intent.
`void`	`requestSingleUpdate(String provider, LocationListener listener, Looper looper)` Register for a single location update using the named provider and a callback.
`void`	`requestSingleUpdate(Criteria criteria, LocationListener listener, Looper looper)` Register for a single location update using a Criteria and a callback.
`boolean`	`sendExtraCommand(String provider, String command, Bundle extras)` Sends additional commands to a location provider.
`void`	`setTestProviderEnabled(String provider, boolean enabled)` Sets a mock enabled value for the given provider.
`void`	`setTestProviderLocation(String provider, Location loc)` Sets a mock location for the given provider.
`void`	`setTestProviderStatus(String provider, int status, Bundle extras, long updateTime)` This method was deprecated in API level Q. This method has no effect.
`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.
`final Class<?>`	`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 timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void`	`wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void`	`wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

Constants

GPS_PROVIDER

Added in API level 1

public static final String GPS_PROVIDER

Name of the GPS location provider.

This provider determines location using satellites. Depending on conditions, this provider may take a while to return a location fix. Requires the permission Manifest.permission.ACCESS_FINE_LOCATION.

The extras Bundle for the GPS location provider can contain the following key/value pairs:

satellites - the number of satellites used to derive the fix

Constant Value: "gps"

KEY_LOCATION_CHANGED

Added in API level 3

public static final String KEY_LOCATION_CHANGED

Key used for a Bundle extra holding a Location value when a location change is broadcast using a PendingIntent.

Constant Value: "location"

KEY_PROVIDER_ENABLED

Added in API level 3

public static final String KEY_PROVIDER_ENABLED

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

Constant Value: "providerEnabled"

KEY_PROXIMITY_ENTERING

Added in API level 1

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

Added in API level 3
Deprecated in API level Q

public static final String KEY_STATUS_CHANGED

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

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

Added in API level 19

public static final String MODE_CHANGED_ACTION

Broadcast intent action when the device location mode changes. To check the location mode, use isLocationEnabled().

Constant Value: "android.location.MODE_CHANGED"

NETWORK_PROVIDER

Added in API level 1

public static final String NETWORK_PROVIDER

Name of the network location provider.

This provider determines location based on availability of cell tower and WiFi access points. Results are retrieved by means of a network lookup.

Constant Value: "network"

PASSIVE_PROVIDER

Added in API level 8

public static final String PASSIVE_PROVIDER

A special location provider for receiving locations without actually initiating a location fix.

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 return locations generated by other providers. You can query the Location#getProvider() method to determine the origin of the location update. Requires the permission Manifest.permission.ACCESS_FINE_LOCATION, although if the GPS is not enabled this provider might only return coarse fixes.

Constant Value: "passive"

PROVIDERS_CHANGED_ACTION

Added in API level 9

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(java.lang.String).

Constant Value: "android.location.PROVIDERS_CHANGED"

Public methods

addGpsStatusListener

Added in API level 3
Deprecated in API level 24

public boolean addGpsStatusListener (GpsStatus.Listener listener)

This method was deprecated in API level 24.
use registerGnssStatusCallback(android.location.GnssStatus.Callback) instead.

Adds a GPS status listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`listener`	`GpsStatus.Listener`: GPS status listener object to register

Returns
`boolean`	true if the listener was successfully added

Throws
`SecurityException`	if the ACCESS_FINE_LOCATION permission is not present

addNmeaListener

Added in API level 24

public boolean addNmeaListener (OnNmeaMessageListener listener, 
                Handler handler)

Adds an NMEA listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`listener`	`OnNmeaMessageListener`: a `OnNmeaMessageListener` object to register
`handler`	`Handler`: the handler that the listener runs on.

Returns
`boolean`	true if the listener was successfully added

Throws
`SecurityException`	if the ACCESS_FINE_LOCATION permission is not present

addNmeaListener

Added in API level 24

public boolean addNmeaListener (OnNmeaMessageListener listener)

Adds an NMEA listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`listener`	`OnNmeaMessageListener`: a `OnNmeaMessageListener` object to register

Returns
`boolean`	true if the listener was successfully added

Throws
`SecurityException`	if the ACCESS_FINE_LOCATION permission is not present

addNmeaListener

Added in API level 5
Deprecated in API level 24

public boolean addNmeaListener (GpsStatus.NmeaListener listener)

This method was deprecated in API level 24.
use addNmeaListener(android.location.OnNmeaMessageListener) instead.

Adds an NMEA listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`listener`	`GpsStatus.NmeaListener`: a `GpsStatus.NmeaListener` object to register

Returns
`boolean`	true if the listener was successfully added

Throws
`SecurityException`	if the ACCESS_FINE_LOCATION permission is not present

addProximityAlert

Added in API level 1

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

Set 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 used to create an Intent to be fired.

The fired Intent will have a boolean extra added with key KEY_PROXIMITY_ENTERING. 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.

After the number of milliseconds given by the expiration parameter, the location manager will delete this proximity alert and no longer monitor it. A value of -1 indicates that there should be no expiration time.

Internally, this method uses both NETWORK_PROVIDER and GPS_PROVIDER.

Before API version 17, this method could be used with Manifest.permission.ACCESS_FINE_LOCATION or Manifest.permission.ACCESS_COARSE_LOCATION. From API version 17 and onwards, this method requires Manifest.permission.ACCESS_FINE_LOCATION permission.
Requires Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION

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`: time for this proximity alert, in milliseconds, or -1 to indicate no expiration
`intent`	`PendingIntent`: a PendingIntent that will be used to generate an Intent to fire when entry to or exit from the alert region is detected

Throws
`SecurityException`	if `Manifest.permission.ACCESS_FINE_LOCATION` permission is not present

addTestProvider

Added in API level 3

public void addTestProvider (String name, 
                boolean requiresNetwork, 
                boolean requiresSatellite, 
                boolean requiresCell, 
                boolean hasMonetaryCost, 
                boolean supportsAltitude, 
                boolean supportsSpeed, 
                boolean supportsBearing, 
                int powerRequirement, 
                int accuracy)

Creates a mock location provider and adds it to the set of active providers.

Parameters
`name`	`String`: the provider name
`requiresNetwork`	`boolean`
`requiresSatellite`	`boolean`
`requiresCell`	`boolean`
`hasMonetaryCost`	`boolean`
`supportsAltitude`	`boolean`
`supportsSpeed`	`boolean`
`supportsBearing`	`boolean`
`powerRequirement`	`int`
`accuracy`	`int`

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if a provider with the given name already exists

clearTestProviderEnabled

Added in API level 3
Deprecated in API level Q

public void clearTestProviderEnabled (String provider)

This method was deprecated in API level Q.
Use setTestProviderEnabled(java.lang.String, boolean) instead.

Removes any mock enabled value associated with the given provider.

Parameters
`provider`	`String`: the provider name

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists

clearTestProviderLocation

Added in API level 3
Deprecated in API level Q

public void clearTestProviderLocation (String provider)

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

Removes any mock location associated with the given provider.

Parameters
`provider`	`String`: the provider name

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists

clearTestProviderStatus

Added in API level 3
Deprecated in API level Q

public void clearTestProviderStatus (String provider)

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

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

Parameters
`provider`	`String`: the provider name

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists

getAllProviders

Added in API level 1

public List<String> getAllProviders ()

Returns a list of the names of all known location providers.

All providers are returned, including ones that are not permitted to be accessed by the calling activity or are currently disabled.

Returns
`List<String>`	list of Strings containing names of the provider

getBestProvider

Added in API level 1

public String getBestProvider (Criteria criteria, 
                boolean enabledOnly)

Returns the name of the provider that best meets the given criteria. Only providers that are permitted to be accessed by the calling activity 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 sequence:

power requirement
accuracy
bearing
speed
altitude

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

Parameters
`criteria`	`Criteria`: the criteria that need to be matched
`enabledOnly`	`boolean`: if true then only a provider that is currently enabled is returned

Returns
`String`	name of the provider that best matches the requirements

getGnssHardwareModelName

Added in API level 28

public String getGnssHardwareModelName ()

Returns the Model Name (including Vendor and Hardware/Software Version) of the GNSS hardware driver.

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

Will return null when the GNSS hardware abstraction layer does not support providing this value.

Returns
`String`

getGnssYearOfHardware

Added in API level 28

public int getGnssYearOfHardware ()

Returns the model year of the GNSS hardware and software build.

More details, such as build date, may be available in getGnssHardwareModelName().

May return 0 if the model year is less than 2016.

Returns
`int`

getGpsStatus

Added in API level 3
Deprecated in API level 24

public GpsStatus getGpsStatus (GpsStatus status)

Retrieves information about the current status of the GPS engine. This should only be called from the GpsStatus.Listener#onGpsStatusChanged callback to ensure that the data is copied atomically. The caller may either pass in a GpsStatus object to set with the latest status information, or pass null to create a new GpsStatus object.
Requires Manifest.permission.ACCESS_FINE_LOCATION

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

Returns
`GpsStatus`	status object containing updated GPS status.

getLastKnownLocation

Added in API level 1

public Location getLastKnownLocation (String provider)

Returns a Location indicating the data from the last known location fix obtained from the given provider.

This can be done without starting the provider. Note that this location could be out-of-date, for example if the device was turned off and moved to another location.

If the provider is currently disabled, null is returned.
Requires Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`provider`	`String`: the name of the provider

Returns
`Location`	the last known location for the provider, or null

Throws
`SecurityException`	if no suitable permission is present
`IllegalArgumentException`	if provider is null or doesn't exist

getProvider

Added in API level 1

public LocationProvider getProvider (String name)

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

Parameters
`name`	`String`: the provider name

Returns
`LocationProvider`	a LocationProvider, or null

Throws
`IllegalArgumentException`	if name is null or does not exist
`SecurityException`	if the caller is not permitted to access the given provider.

getProviders

Added in API level 1

public List<String> getProviders (boolean enabledOnly)

Returns a list of the names of location providers.

Parameters
`enabledOnly`	`boolean`: if true then only the providers which are currently enabled are returned.

Returns
`List<String>`	list of Strings containing names of the providers

getProviders

Added in API level 1

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

Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do. Only providers that are permitted to be accessed by the calling activity will be returned.

Parameters
`criteria`	`Criteria`: the criteria that the returned providers must match
`enabledOnly`	`boolean`: if true then only the providers which are currently enabled are returned.

Returns
`List<String>`	list of Strings containing names of the providers

isLocationEnabled

Added in API level 28

public boolean isLocationEnabled ()

Returns the current enabled/disabled state of location. To listen for changes, see MODE_CHANGED_ACTION.

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

isProviderEnabled

Added in API level 1

public boolean isProviderEnabled (String provider)

Returns the current enabled/disabled status of the given provider. To listen for changes, see PROVIDERS_CHANGED_ACTION. Before API version Build.VERSION_CODES.LOLLIPOP, this method would throw SecurityException if the location permissions were not sufficient to use the specified provider.

Parameters
`provider`	`String`: the name of the provider

Returns
`boolean`	true if the provider exists and is enabled

Throws
`IllegalArgumentException`	if provider is null

registerGnssMeasurementsCallback

Added in API level 24

public boolean registerGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback)

Registers a GPS Measurement callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`callback`	`GnssMeasurementsEvent.Callback`: a `GnssMeasurementsEvent.Callback` object to register.

Returns
`boolean`	`true` if the callback was added successfully, `false` otherwise.

registerGnssMeasurementsCallback

Added in API level 24

public boolean registerGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback, 
                Handler handler)

Registers a GPS Measurement callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`callback`	`GnssMeasurementsEvent.Callback`: a `GnssMeasurementsEvent.Callback` object to register.
`handler`	`Handler`: the handler that the callback runs on.

Returns
`boolean`	`true` if the callback was added successfully, `false` otherwise.

registerGnssNavigationMessageCallback

Added in API level 24

public boolean registerGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback, 
                Handler handler)

Registers a GNSS Navigation Message callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`callback`	`GnssNavigationMessage.Callback`: a `GnssNavigationMessage.Callback` object to register.
`handler`	`Handler`: the handler that the callback runs on.

Returns
`boolean`	`true` if the callback was added successfully, `false` otherwise.

registerGnssNavigationMessageCallback

Added in API level 24

public boolean registerGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)

Registers a GNSS Navigation Message callback.

Parameters
`callback`	`GnssNavigationMessage.Callback`: a `GnssNavigationMessage.Callback` object to register.

Returns
`boolean`	`true` if the callback was added successfully, `false` otherwise.

registerGnssStatusCallback

Added in API level 24

public boolean registerGnssStatusCallback (GnssStatus.Callback callback)

Registers a GNSS status callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`callback`	`GnssStatus.Callback`: GNSS status callback object to register

Returns
`boolean`	true if the listener was successfully added

Throws
`SecurityException`	if the ACCESS_FINE_LOCATION permission is not present

registerGnssStatusCallback

Added in API level 24

public boolean registerGnssStatusCallback (GnssStatus.Callback callback, 
                Handler handler)

Registers a GNSS status callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`callback`	`GnssStatus.Callback`: GNSS status callback object to register
`handler`	`Handler`: the handler that the callback runs on.

Returns
`boolean`	true if the listener was successfully added

Throws
`SecurityException`	if the ACCESS_FINE_LOCATION permission is not present

removeGpsStatusListener

Added in API level 3
Deprecated in API level 24

public void removeGpsStatusListener (GpsStatus.Listener listener)

This method was deprecated in API level 24.
use unregisterGnssStatusCallback(android.location.GnssStatus.Callback) instead.

Removes a GPS status listener.

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

removeNmeaListener

Added in API level 24

public void removeNmeaListener (OnNmeaMessageListener listener)

Removes an NMEA listener.

Parameters
`listener`	`OnNmeaMessageListener`: a `OnNmeaMessageListener` object to remove

removeNmeaListener

Added in API level 5
Deprecated in API level 24

public void removeNmeaListener (GpsStatus.NmeaListener listener)

This method was deprecated in API level 24.
use removeNmeaListener(android.location.OnNmeaMessageListener) instead.

Removes an NMEA listener.

Parameters
`listener`	`GpsStatus.NmeaListener`: a `GpsStatus.NmeaListener` object to remove

removeProximityAlert

Added in API level 1

public void removeProximityAlert (PendingIntent intent)

Removes the proximity alert with the given PendingIntent.

Parameters
`intent`	`PendingIntent`: the PendingIntent that no longer needs to be notified of proximity alerts

Throws
`IllegalArgumentException`	if intent is null
`SecurityException`	if `Manifest.permission.ACCESS_FINE_LOCATION` permission is not present

removeTestProvider

Added in API level 3

public void removeTestProvider (String provider)

Removes the mock location provider with the given name.

Parameters
`provider`	`String`: the provider name

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists

removeUpdates

Added in API level 1

public void removeUpdates (LocationListener listener)

Removes all location updates for the specified LocationListener.

Following this call, updates will no longer occur for this listener.
Requires Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`listener`	`LocationListener`: listener object that no longer needs location updates

Throws
`IllegalArgumentException`	if listener is null

removeUpdates

Added in API level 3

public void removeUpdates (PendingIntent intent)

Removes all location updates for the specified pending intent.

Following this call, updates will no longer for this pending intent.

Parameters
`intent`	`PendingIntent`: pending intent object that no longer needs location updates

Throws
`IllegalArgumentException`	if intent is null

requestLocationUpdates

Added in API level 1

public void requestLocationUpdates (String provider, 
                long minTime, 
                float minDistance, 
                LocationListener listener)

See requestLocationUpdates(long, float, android.location.Criteria, android.app.PendingIntent) for more detail on how to use this method.
Requires Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`provider`	`String`: the name of the provider with which to register
`minTime`	`long`: minimum time interval between location updates, in milliseconds
`minDistance`	`float`: minimum distance between location updates, in meters
`listener`	`LocationListener`: a `LocationListener` whose `LocationListener#onLocationChanged` method will be called for each location update

Throws
`IllegalArgumentException`	if provider is null or doesn't exist on this device
`IllegalArgumentException`	if listener is null
`RuntimeException`	if the calling thread has no Looper
`SecurityException`	if no suitable permission is present

requestLocationUpdates

Added in API level 9

public void requestLocationUpdates (long minTime, 
                float minDistance, 
                Criteria criteria, 
                LocationListener listener, 
                Looper looper)

Parameters
`minTime`	`long`: minimum time interval between location updates, in milliseconds
`minDistance`	`float`: minimum distance between location updates, in meters
`criteria`	`Criteria`: contains parameters for the location manager to choose the appropriate provider and parameters to compute the location
`listener`	`LocationListener`: a `LocationListener` whose `LocationListener#onLocationChanged` method will be called for each location update
`looper`	`Looper`: a Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on the calling thread

Throws
`IllegalArgumentException`	if criteria is null
`IllegalArgumentException`	if listener is null
`SecurityException`	if no suitable permission is present

requestLocationUpdates

Added in API level 1

public void requestLocationUpdates (String provider, 
                long minTime, 
                float minDistance, 
                LocationListener listener, 
                Looper looper)

Parameters
`provider`	`String`: the name of the provider with which to register
`minTime`	`long`: minimum time interval between location updates, in milliseconds
`minDistance`	`float`: minimum distance between location updates, in meters
`listener`	`LocationListener`: a `LocationListener` whose `LocationListener#onLocationChanged` method will be called for each location update
`looper`	`Looper`: a Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on 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

Added in API level 9

public void requestLocationUpdates (long minTime, 
                float minDistance, 
                Criteria criteria, 
                PendingIntent intent)

The requestLocationUpdates() and requestSingleUpdate() register the current activity to be updated periodically by the named provider, or by the provider matching the specified Criteria, with location and status updates.

It may take a while to receive the first location update. If an immediate location is required, applications may use the getLastKnownLocation(java.lang.String) method.

Location updates are received either by LocationListener callbacks, or by broadcast intents to a supplied PendingIntent.

If the caller supplied a pending intent, then location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value.

The location update interval can be controlled using the minTime parameter. The elapsed time between location updates will never be less than minTime, although it can be more depending on the Location Provider implementation and the update interval requested by other applications.

Choosing a sensible value for minTime is important to conserve battery life. Each location update requires power from GPS, WIFI, Cell and other radios. Select a minTime value as high as possible while still providing a reasonable user experience. If your application is not in the foreground and showing location to the user then your application should avoid using an active provider (such as NETWORK_PROVIDER or GPS_PROVIDER), but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) or greater. If your application is in the foreground and showing location to the user then it is appropriate to select a faster update interval.

The minDistance parameter can also be used to control the frequency of location updates. If it is greater than 0 then the location provider will only send your application an update when the location has changed by at least minDistance meters, AND at least minTime milliseconds have passed. However it is more difficult for location providers to save power using the minDistance parameter, so minTime should be the primary tool to conserving battery life.

If your application wants to passively observe location updates triggered by other applications, but not consume any additional power otherwise, then use the PASSIVE_PROVIDER This provider does not actively turn on or modify active location providers, so you do not need to be as careful about minTime and minDistance. However if your application performs heavy work on a location update (such as network activity) then you should select non-zero values for minTime and/or minDistance to rate-limit your update frequency in the case another application enables a location provider with extremely fast updates.

In case the provider is disabled by the user, updates will stop, and a provider availability update will be sent. As soon as the provider is enabled again, location updates will immediately resume and a provider availability update sent. Providers can also send status updates, at any time, with extra's specific to the provider. If a callback was supplied then status and availability updates are via LocationListener#onProviderDisabled, LocationListener#onProviderEnabled or LocationListener#onStatusChanged. Alternately, if a pending intent was supplied then status and availability updates are broadcast intents with extra keys of KEY_PROVIDER_ENABLED or KEY_STATUS_CHANGED.

If a LocationListener is used but with no Looper specified then the calling thread must already be a Looper thread such as the main thread of the calling Activity. If a Looper is specified with a LocationListener then callbacks are made on the supplied Looper thread.

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.

Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. From Jellybean and onwards it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.
Requires Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION

Parameters
`minTime`	`long`: minimum time interval between location updates, in milliseconds
`minDistance`	`float`: minimum distance between location updates, in meters
`criteria`	`Criteria`: contains parameters for the location manager to choose the appropriate provider and parameters to compute the location
`intent`	`PendingIntent`: a `PendingIntent` to be sent for each location update

Throws
`IllegalArgumentException`	if criteria is null
`IllegalArgumentException`	if intent is null
`SecurityException`	if no suitable permission is present

requestLocationUpdates

Added in API level 3

public void requestLocationUpdates (String provider, 
                long minTime, 
                float minDistance, 
                PendingIntent intent)

Parameters
`provider`	`String`: the name of the provider with which to register
`minTime`	`long`: minimum time interval between location updates, in milliseconds
`minDistance`	`float`: minimum distance between location updates, in meters
`intent`	`PendingIntent`: a `PendingIntent` to be sent for each location update

Throws
`IllegalArgumentException`	if provider is null or doesn't exist on this device
`IllegalArgumentException`	if intent is null
`SecurityException`	if no suitable permission is present

requestSingleUpdate

Added in API level 9

public void requestSingleUpdate (String provider, 
                PendingIntent intent)

Parameters
`provider`	`String`: the name of the provider with which to register
`intent`	`PendingIntent`: a `PendingIntent` to be sent for the location update

Throws
`IllegalArgumentException`	if provider is null or doesn't exist
`IllegalArgumentException`	if intent is null
`SecurityException`	if no suitable permission is present

requestSingleUpdate

Added in API level 9

public void requestSingleUpdate (Criteria criteria, 
                PendingIntent intent)

Parameters
`criteria`	`Criteria`: contains parameters for the location manager to choose the appropriate provider and parameters to compute the location
`intent`	`PendingIntent`: a `PendingIntent` to be sent for the location update

Throws
`IllegalArgumentException`	if provider is null or doesn't exist
`IllegalArgumentException`	if intent is null
`SecurityException`	if no suitable permission is present

requestSingleUpdate

Added in API level 9

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

Parameters
`provider`	`String`: the name of the provider with which to register
`listener`	`LocationListener`: a `LocationListener` whose `LocationListener#onLocationChanged` method will be called when the location update is available
`looper`	`Looper`: a Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on 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

Added in API level 9

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

Parameters
`criteria`	`Criteria`: contains parameters for the location manager to choose the appropriate provider and parameters to compute the location
`listener`	`LocationListener`: a `LocationListener` whose `LocationListener#onLocationChanged` method will be called when the location update is available
`looper`	`Looper`: a Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on the calling thread

Throws
`IllegalArgumentException`	if criteria is null
`IllegalArgumentException`	if listener is null
`SecurityException`	if no suitable permission is present

sendExtraCommand

Added in API level 3

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`: name of the location provider.
`command`	`String`: name of the command to send to the provider.
`extras`	`Bundle`: optional arguments for the command (or null). The provider may optionally fill the extras Bundle with results from the command.

Returns
`boolean`	true if the command succeeds.

setTestProviderEnabled

Added in API level 3

public void setTestProviderEnabled (String provider, 
                boolean enabled)

Sets a mock enabled value for the given provider. This value will be used in place of any actual value from the provider.

Parameters
`provider`	`String`: the provider name
`enabled`	`boolean`: the mock enabled value

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists

setTestProviderLocation

Added in API level 3

public void setTestProviderLocation (String provider, 
                Location loc)

Sets a mock location for the given provider.

This location will be used in place of any actual location from the provider. The location object must have a minimum number of fields set to be considered a valid LocationProvider Location, as per documentation on Location class.

Parameters
`provider`	`String`: the provider name
`loc`	`Location`: the mock location

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists
`IllegalArgumentException`	if the location is incomplete

setTestProviderStatus

Added in API level 3
Deprecated in API level Q

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

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

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

Parameters
`provider`	`String`: the provider name
`status`	`int`: the mock status
`extras`	`Bundle`: a Bundle containing mock extras
`updateTime`	`long`: the mock update time

Throws
`SecurityException`	if `mock location app op` is not set to `allowed` for your app.
`IllegalArgumentException`	if no provider with the given name exists

unregisterGnssMeasurementsCallback

Added in API level 24

public void unregisterGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback)

Unregisters a GPS Measurement callback.

Parameters
`callback`	`GnssMeasurementsEvent.Callback`: a `GnssMeasurementsEvent.Callback` object to remove.

unregisterGnssNavigationMessageCallback

Added in API level 24

public void unregisterGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)

Unregisters a GNSS Navigation Message callback.

Parameters
`callback`	`GnssNavigationMessage.Callback`: a `GnssNavigationMessage.Callback` object to remove.

unregisterGnssStatusCallback

Added in API level 24

public void unregisterGnssStatusCallback (GnssStatus.Callback callback)

Removes a GNSS status callback.

Parameters
`callback`	`GnssStatus.Callback`: GNSS status callback object to remove