LocationManager

GPS_PROVIDER

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 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

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

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

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

String KEY_STATUS_CHANGED

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

String MODE_CHANGED_ACTION

Broadcast intent action when LOCATION_MODE changes. For use with the LOCATION_MODE API. If you're interacting with isProviderEnabled(String), use PROVIDERS_CHANGED_ACTION instead. In the future, there may be mode changes that do not result in PROVIDERS_CHANGED_ACTION broadcasts.

Constant Value: "android.location.MODE_CHANGED"

NETWORK_PROVIDER

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

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 getProvider() method to determine the origin of the location update. Requires the permission ACCESS_FINE_LOCATION, although if the GPS is not enabled this provider might only return coarse fixes.

Constant Value: "passive"

PROVIDERS_CHANGED_ACTION

String PROVIDERS_CHANGED_ACTION

Broadcast intent action when the configured location providers change. For use with isProviderEnabled(String). If you're interacting with the LOCATION_MODE API, use MODE_CHANGED_ACTION instead.

Constant Value: "android.location.PROVIDERS_CHANGED"

addGpsStatusListener

boolean addGpsStatusListener (GpsStatus.Listener listener)

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

Adds a GPS status listener.

addNmeaListener

boolean addNmeaListener (OnNmeaMessageListener listener, 
                Handler handler)

Adds an NMEA listener.

addNmeaListener

boolean addNmeaListener (OnNmeaMessageListener listener)

Adds an NMEA listener.

addNmeaListener

boolean addNmeaListener (GpsStatus.NmeaListener listener)

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

Adds an NMEA listener.

addProximityAlert

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 ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION. From API version 17 and onwards, this method requires ACCESS_FINE_LOCATION permission.

addTestProvider

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.

clearTestProviderEnabled

void clearTestProviderEnabled (String provider)

Removes any mock enabled value associated with the given provider.

clearTestProviderLocation

void clearTestProviderLocation (String provider)

Removes any mock location associated with the given provider.

clearTestProviderStatus

void clearTestProviderStatus (String provider)

Removes any mock status values associated with the given provider.

getAllProviders

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.

getBestProvider

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.

getGpsStatus

GpsStatus getGpsStatus (GpsStatus status)

Retrieves information about the current status of the GPS engine. This should only be called from the onGpsStatusChanged(int) 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.

getLastKnownLocation

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.

getProvider

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.

getProviders

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.

getProviders

List<String> getProviders (boolean enabledOnly)

Returns a list of the names of location providers.

isProviderEnabled

boolean isProviderEnabled (String provider)

Returns the current enabled/disabled status of the given provider.

If the user has enabled this provider in the Settings menu, true is returned otherwise false is returned

Callers should instead use LOCATION_MODE unless they depend on provider-specific APIs such as requestLocationUpdates(String, long, float, LocationListener).

Before API version LOLLIPOP, this method would throw SecurityException if the location permissions were not sufficient to use the specified provider.

registerGnssMeasurementsCallback

boolean registerGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback, 
                Handler handler)

Registers a GPS Measurement callback.

registerGnssMeasurementsCallback

boolean registerGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback)

Registers a GPS Measurement callback.

registerGnssNavigationMessageCallback

boolean registerGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback, 
                Handler handler)

Registers a GNSS Navigation Message callback.

registerGnssNavigationMessageCallback

boolean registerGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)

Registers a GNSS Navigation Message callback.

registerGnssStatusCallback

boolean registerGnssStatusCallback (GnssStatus.Callback callback)

Registers a GNSS status listener.

registerGnssStatusCallback

boolean registerGnssStatusCallback (GnssStatus.Callback callback, 
                Handler handler)

Registers a GNSS status listener.

removeGpsStatusListener

void removeGpsStatusListener (GpsStatus.Listener listener)

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

Removes a GPS status listener.

removeNmeaListener

void removeNmeaListener (OnNmeaMessageListener listener)

Removes an NMEA listener.

removeNmeaListener

void removeNmeaListener (GpsStatus.NmeaListener listener)

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

Removes an NMEA listener.

removeProximityAlert

void removeProximityAlert (PendingIntent intent)

Removes the proximity alert with the given PendingIntent.

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

removeTestProvider

void removeTestProvider (String provider)

Removes the mock location provider with the given name.

removeUpdates

void removeUpdates (LocationListener listener)

Removes all location updates for the specified LocationListener.

Following this call, updates will no longer occur for this listener.

removeUpdates

void removeUpdates (PendingIntent intent)

Removes all location updates for the specified pending intent.

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

requestLocationUpdates

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

Register for location updates using the named provider, and a pending intent.

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestLocationUpdates

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.

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestLocationUpdates

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

Register for location updates using a Criteria and pending 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(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 onProviderDisabled(String), onProviderEnabled(String) or onStatusChanged(String, int, Bundle). 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.

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.

requestLocationUpdates

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.

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestLocationUpdates

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

Register for location updates using the named provider, and a pending intent.

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestSingleUpdate

void requestSingleUpdate (String provider, 
                PendingIntent intent)

Register for a single location update using a named provider and pending intent.

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestSingleUpdate

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

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

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestSingleUpdate

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

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

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

requestSingleUpdate

void requestSingleUpdate (Criteria criteria, 
                PendingIntent intent)

Register for a single location update using a Criteria and pending intent.

See requestLocationUpdates(long, float, Criteria, PendingIntent) for more detail on how to use this method.

sendExtraCommand

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

setTestProviderEnabled

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.

setTestProviderLocation

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.

setTestProviderStatus

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

Sets mock status values for the given provider. These values will be used in place of any actual values from the provider.

unregisterGnssMeasurementsCallback

void unregisterGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback)

Unregisters a GPS Measurement callback.

unregisterGnssNavigationMessageCallback

void unregisterGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)

Unregisters a GNSS Navigation Message callback.

unregisterGnssStatusCallback

void unregisterGnssStatusCallback (GnssStatus.Callback callback)

Removes a GNSS status listener.