public class

LocationManager

extends Object
java.lang.Object
   ↳ android.location.LocationManager

Class Overview

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.

You do not instantiate this class directly; instead, retrieve it through Context.getSystemService(Context.LOCATION_SERVICE).

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 Key used for a Bundle extra holding an Integer status value when a status change is broadcast using a PendingIntent.
String NETWORK_PROVIDER Name of the network location provider.
Public Methods
boolean addGpsStatusListener(GpsStatus.Listener listener)
Adds a GPS status listener.
void addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent)
Sets 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)
Removes any mock enabled value associated with the given provider.
void clearTestProviderLocation(String provider)
Removes any mock location associated with the given provider.
void clearTestProviderStatus(String provider)
Removes any mock status values associated with the given provider.
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.
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(Criteria criteria, boolean enabledOnly)
Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do.
List<String> getProviders(boolean enabledOnly)
Returns a list of the names of location providers.
boolean isProviderEnabled(String provider)
Returns the current enabled/disabled status of the given provider.
void removeGpsStatusListener(GpsStatus.Listener listener)
Removes a GPS status listener.
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 any current registration for location updates of the current activity with the given LocationListener.
void removeUpdates(PendingIntent intent)
Removes any current registration for location updates of the current activity with the given PendingIntent.
void requestLocationUpdates(String provider, long minTime, float minDistance, PendingIntent intent)
Registers the current activity to be notified periodically by the named provider.
void requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener)
Registers the current activity to be notified periodically by the named provider.
void requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener, Looper looper)
Registers the current activity to be notified periodically by the named provider.
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)
Sets mock status values for the given provider.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

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 android.permissions.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"

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"

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"

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"

public static final 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"

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. Requires either of the permissions android.permission.ACCESS_COARSE_LOCATION or android.permission.ACCESS_FINE_LOCATION.

Constant Value: "network"

Public Methods

public boolean addGpsStatusListener (GpsStatus.Listener listener)

Adds a GPS status listener.

Parameters
listener GPS status listener object to register
Returns
  • true if the listener was successfully added
Throws
SecurityException if the ACCESS_FINE_LOCATION permission is not present

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

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

In case the screen goes to sleep, checks for proximity alerts happen only once every 4 minutes. This conserves battery life by ensuring that the device isn't perpetually awake.

Internally, this method uses both NETWORK_PROVIDER and GPS_PROVIDER.

Parameters
latitude the latitude of the central point of the alert region
longitude the longitude of the central point of the alert region
radius the radius of the central point of the alert region, in meters
expiration time for this proximity alert, in milliseconds, or -1 to indicate no expiration
intent 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 no permission exists for the required providers.

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 the provider name
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled
IllegalArgumentException if a provider with the given name already exists

public void clearTestProviderEnabled (String provider)

Removes any mock enabled value associated with the given provider.

Parameters
provider the provider name
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists

public void clearTestProviderLocation (String provider)

Removes any mock location associated with the given provider.

Parameters
provider the provider name
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists

public void clearTestProviderStatus (String provider)

Removes any mock status values associated with the given provider.

Parameters
provider the provider name
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists

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 of Strings containing names of the providers

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 the criteria that need to be matched
enabledOnly if true then only a provider that is currently enabled is returned
Returns
  • name of the provider that best matches the requirements

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

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

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.

Parameters
provider the name of the provider
Returns
  • the last known location for the provider, or null
Throws
SecurityException if no suitable permission is present for the provider.
IllegalArgumentException if provider is null or doesn't exist

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 the provider name
Returns
  • a LocationProvider, or null
Throws
IllegalArgumentException if name is null
SecurityException if the caller is not permitted to access the given provider.

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 the criteria that the returned providers must match
enabledOnly if true then only the providers which are currently enabled are returned.
Returns
  • list of Strings containing names of the providers

public List<String> getProviders (boolean enabledOnly)

Returns a list of the names of location providers. Only providers that are permitted to be accessed by the calling activity will be returned.

Parameters
enabledOnly if true then only the providers which are currently enabled are returned.
Returns
  • list of Strings containing names of the providers

public 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

Parameters
provider the name of the provider
Returns
  • true if the provider is enabled
Throws
SecurityException if no suitable permission is present for the provider.
IllegalArgumentException if provider is null or doesn't exist

public void removeGpsStatusListener (GpsStatus.Listener listener)

Removes a GPS status listener.

Parameters
listener GPS status listener object to remove

public void removeProximityAlert (PendingIntent intent)

Removes the proximity alert with the given PendingIntent.

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

public void removeTestProvider (String provider)

Removes the mock location provider with the given name.

Parameters
provider the provider name
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists

public void removeUpdates (LocationListener listener)

Removes any current registration for location updates of the current activity with the given LocationListener. Following this call, updates will no longer occur for this listener.

Parameters
listener {#link LocationListener} object that no longer needs location updates
Throws
IllegalArgumentException if listener is null

public void removeUpdates (PendingIntent intent)

Removes any current registration for location updates of the current activity with the given PendingIntent. Following this call, updates will no longer occur for this intent.

Parameters
intent {#link PendingIntent} object that no longer needs location updates
Throws
IllegalArgumentException if intent is null

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

Registers the current activity to be notified periodically by the named provider. Periodically, the supplied PendingIntent will be broadcast with the current Location or with status updates.

Location updates are sent with a key of KEY_LOCATION_CHANGED and a Location value.

It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.

The frequency of notification or new locations may be controlled using the minTime and minDistance parameters. If minTime is greater than 0, the LocationManager could potentially rest for minTime milliseconds between location updates to conserve power. If minDistance is greater than 0, a location will only be broadcast if the device moves by minDistance meters. To obtain notifications as frequently as possible, set both parameters to 0.

Background services should be careful about setting a sufficiently high minTime so that the device doesn't consume too much power by keeping the GPS or wireless radios on all the time. In particular, values under 60000ms are not recommended.

In case the provider is disabled by the user, updates will stop, and an intent will be sent with an extra with key KEY_PROVIDER_ENABLED and a boolean value of false. If the provider is re-enabled, an intent will be sent with an extra with key KEY_PROVIDER_ENABLED and a boolean value of true and location updates will start again.

If the provider's status changes, an intent will be sent with an extra with key KEY_STATUS_CHANGED and an integer value indicating the new status. Any extras associated with the status update will be sent as well.

Parameters
provider the name of the provider with which to register
minTime the minimum time interval for notifications, in milliseconds. This field is only used as a hint to conserve power, and actual time between location updates may be greater or lesser than this value.
minDistance the minimum distance interval for notifications, in meters
intent a {#link PendingIntet} to be sent for each location update
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if intent is null
SecurityException if no suitable permission is present for the provider.

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

Registers the current activity to be notified periodically by the named provider. Periodically, the supplied LocationListener will be called with the current Location or with status updates.

It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.

In case the provider is disabled by the user, updates will stop, and the onProviderDisabled(String) method will be called. As soon as the provider is enabled again, the onProviderEnabled(String) method will be called and location updates will start again.

The frequency of notification may be controlled using the minTime and minDistance parameters. If minTime is greater than 0, the LocationManager could potentially rest for minTime milliseconds between location updates to conserve power. If minDistance is greater than 0, a location will only be broadcasted if the device moves by minDistance meters. To obtain notifications as frequently as possible, set both parameters to 0.

Background services should be careful about setting a sufficiently high minTime so that the device doesn't consume too much power by keeping the GPS or wireless radios on all the time. In particular, values under 60000ms are not recommended.

The calling thread must be a Looper thread such as the main thread of the calling Activity.

Parameters
provider the name of the provider with which to register
minTime the minimum time interval for notifications, in milliseconds. This field is only used as a hint to conserve power, and actual time between location updates may be greater or lesser than this value.
minDistance the minimum distance interval for notifications, in meters
listener a {#link LocationListener} whose onLocationChanged(Location) method will be called for each location update
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 for the provider.

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

Registers the current activity to be notified periodically by the named provider. Periodically, the supplied LocationListener will be called with the current Location or with status updates.

It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.

In case the provider is disabled by the user, updates will stop, and the onProviderDisabled(String) method will be called. As soon as the provider is enabled again, the onProviderEnabled(String) method will be called and location updates will start again.

The frequency of notification may be controlled using the minTime and minDistance parameters. If minTime is greater than 0, the LocationManager could potentially rest for minTime milliseconds between location updates to conserve power. If minDistance is greater than 0, a location will only be broadcasted if the device moves by minDistance meters. To obtain notifications as frequently as possible, set both parameters to 0.

Background services should be careful about setting a sufficiently high minTime so that the device doesn't consume too much power by keeping the GPS or wireless radios on all the time. In particular, values under 60000ms are not recommended.

The supplied Looper is used to implement the callback mechanism.

Parameters
provider the name of the provider with which to register
minTime the minimum time interval for notifications, in milliseconds. This field is only used as a hint to conserve power, and actual time between location updates may be greater or lesser than this value.
minDistance the minimum distance interval for notifications, in meters
listener a {#link LocationListener} whose onLocationChanged(Location) method will be called for each location update
looper a Looper object whose message queue will be used to implement the callback mechanism.
Throws
IllegalArgumentException if provider is null or doesn't exist
IllegalArgumentException if listener is null
IllegalArgumentException if looper is null
SecurityException if no suitable permission is present for the provider.

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

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 the provider name
enabled the mock enabled value
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists

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.

Parameters
provider the provider name
loc the mock location
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists

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

Parameters
provider the provider name
status the mock status
extras a Bundle containing mock extras
updateTime the mock update time
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
IllegalArgumentException if no provider with the given name exists