Added in API level 1

LocationManager

open class LocationManager
kotlin.Any
   ↳ 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 be notified when the device enters the proximity of a given geographical location.

Unless otherwise noted, all Location API methods require the android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION 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 feature which can be detected using PackageManager.hasSystemFeature(String).

Summary

Constants
static String

Broadcast intent action when GNSS capabilities change.
static String

Intent extra included with ACTION_GNSS_CAPABILITIES_CHANGED broadcasts, containing the new GnssCapabilities.
static String

Intent extra included with MODE_CHANGED_ACTION broadcasts, containing the boolean enabled state of location.
static String

Intent extra included with PROVIDERS_CHANGED_ACTION broadcasts, containing the boolean enabled state of the location provider that has changed.
static String

Intent extra included with PROVIDERS_CHANGED_ACTION broadcasts, containing the name of the location provider that has changed.
static String

Standard name of the fused location provider.
static String

Standard name of the GNSS location provider.
static String

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

Key used for an extra holding a array of Locations when a location change is sent using a PendingIntent.
static String

Key used for an extra holding a Location value when a location change is sent using a PendingIntent.
static String

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

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

This key is no longer in use.
static String

Broadcast intent action when the device location enabled state changes.
static String

Standard name of the network location provider.
static String

A special location provider for receiving locations without actively initiating a location fix.
static String

Broadcast intent action when the set of enabled location providers changes.
Public methods
open Boolean

Adds a GPS status listener.
open Boolean

No-op method to keep backward-compatibility.
open Boolean

Adds an NMEA listener.
open Boolean

Adds an NMEA listener.
open Boolean

Adds an NMEA listener.
open Unit
addProximityAlert(latitude: Double, longitude: Double, radius: Float, expiration: Long, pendingIntent: PendingIntent)

Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius.
open Unit
addTestProvider(provider: String, properties: ProviderProperties)

Creates a test location provider and adds it to the set of active providers.
open Unit
addTestProvider(provider: String, properties: ProviderProperties, extraAttributionTags: MutableSet<String!>)

Creates a test location provider and adds it to the set of active providers.
open Unit
addTestProvider(provider: String, requiresNetwork: Boolean, requiresSatellite: Boolean, requiresCell: Boolean, hasMonetaryCost: Boolean, supportsAltitude: Boolean, supportsSpeed: Boolean, supportsBearing: Boolean, powerUsage: Int, accuracy: Int)

Creates a test location provider and adds it to the set of active providers.
open Unit

Equivalent to calling setTestProviderEnabled(java.lang.String,boolean) to disable a test provider.
open Unit

Does nothing.
open Unit

This method has no effect as provider status has been deprecated and is no longer supported.
open MutableList<String!>

Returns a list of the names of all available location providers.
open String?
getBestProvider(criteria: Criteria, enabledOnly: Boolean)

Returns the name of the provider that best meets the given criteria.
open Unit
getCurrentLocation(provider: String, locationRequest: LocationRequest, cancellationSignal: CancellationSignal?, executor: Executor, consumer: Consumer<Location!>)

Asynchronously returns a single current location fix from the given provider based on the given LocationRequest.
open Unit
getCurrentLocation(provider: String, cancellationSignal: CancellationSignal?, executor: Executor, consumer: Consumer<Location!>)

Asynchronously returns a single current location fix from the given provider.
open MutableList<GnssAntennaInfo!>?

Returns the current list of GNSS antenna infos, or null if unknown or unsupported.
open GnssCapabilities

Returns the supported capabilities of the GNSS chipset.
open String?

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

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

Retrieves information about the current status of the GPS engine.
open Location?

Gets the last known location from the given provider, or null if there is no last known location.
open LocationProvider?
getProvider(provider: String)

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

Returns the properties of the given provider, or null if the properties are currently unknown.
open MutableList<String!>
getProviders(criteria: Criteria, enabledOnly: Boolean)

Returns a list of the names of available location providers that satisfy the given criteria.
open MutableList<String!>
getProviders(enabledOnly: Boolean)

Returns a list of the names of available location providers.
open Boolean
hasProvider(provider: String)

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

Returns the current enabled/disabled state of location.
open Boolean

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

Registers a GNSS antenna info listener that will receive all changes to antenna info.
open Boolean

Registers a GNSS measurement callback.
open Boolean

Registers a GNSS measurements callback which will run on a binder thread.
open Boolean

Registers a GNSS measurements callback.
open Boolean

Registers a GNSS measurements callback.
open Boolean

Registers a GNSS navigation message callback which will run on a binder thread.
open Boolean

Registers a GNSS navigation message callback.
open Boolean

Registers a GNSS navigation message callback.
open Boolean

Registers a GNSS status callback.
open Boolean

Registers a GNSS status callback.
open Boolean

Registers a GNSS status callback.
open Unit

Removes a GPS status listener.
open Unit

No-op method to keep backward-compatibility.
open Unit

Removes an NMEA listener.
open Unit

Removes the proximity alert with the given PendingIntent.
open Unit

Removes the test location provider with the given name or does nothing if no such test location provider exists.
open Unit
removeUpdates(pendingIntent: PendingIntent)

Removes location updates for the specified PendingIntent.
open Unit

Removes all location updates for the specified LocationListener.
open Unit
requestFlush(provider: String, pendingIntent: PendingIntent, requestCode: Int)

Requests that the given provider flush any batched locations to listeners.
open Unit
requestFlush(provider: String, listener: LocationListener, requestCode: Int)

Requests that the given provider flush any batched locations to listeners.
open Unit
requestLocationUpdates(provider: String, locationRequest: LocationRequest, pendingIntent: PendingIntent)

Register for location updates from the specified provider, using a LocationRequest, and callbacks delivered via the provided PendingIntent.
open Unit
requestLocationUpdates(provider: String, locationRequest: LocationRequest, executor: Executor, listener: LocationListener)

Register for location updates from the specified provider, using a LocationRequest, and a callback on the specified Executor.
open Unit
requestLocationUpdates(provider: String, minTimeMs: Long, minDistanceM: Float, pendingIntent: PendingIntent)

Register for location updates using the named provider, and callbacks delivered via the provided PendingIntent.
open Unit
requestLocationUpdates(provider: String, minTimeMs: Long, minDistanceM: Float, listener: LocationListener)

Register for location updates from the given provider with the given arguments, and a callback on the Looper of the calling thread.
open Unit
requestLocationUpdates(provider: String, minTimeMs: Long, minDistanceM: Float, listener: LocationListener, looper: Looper?)

Register for location updates from the given provider with the given arguments, and a callback on the specified Looper.
open Unit
requestLocationUpdates(provider: String, minTimeMs: Long, minDistanceM: Float, executor: Executor, listener: LocationListener)

Register for location updates using the named provider, and a callback on the specified Executor.
open Unit
requestLocationUpdates(minTimeMs: Long, minDistanceM: Float, criteria: Criteria, pendingIntent: PendingIntent)

Register for location updates using a provider selected through the given Criteria, and callbacks delivered via the provided PendingIntent.
open Unit
requestLocationUpdates(minTimeMs: Long, minDistanceM: Float, criteria: Criteria, listener: LocationListener, looper: Looper?)

Register for location updates using a provider selected through the given Criteria, and a callback on the specified Looper.
open Unit
requestLocationUpdates(minTimeMs: Long, minDistanceM: Float, criteria: Criteria, executor: Executor, listener: LocationListener)

Register for location updates using a provider selected through the given Criteria, and a callback on the specified Executor.
open Unit
requestSingleUpdate(criteria: Criteria, pendingIntent: PendingIntent)

Register for a single location update using a Criteria and pending intent.
open Unit
requestSingleUpdate(criteria: Criteria, listener: LocationListener, looper: Looper?)

Register for a single location update using a Criteria and a callback.
open Unit
requestSingleUpdate(provider: String, pendingIntent: PendingIntent)

Register for a single location update using a named provider and pending intent.
open Unit
requestSingleUpdate(provider: String, listener: LocationListener, looper: Looper?)

Register for a single location update using the named provider and a callback.
open Boolean
sendExtraCommand(provider: String, command: String, extras: Bundle?)

Sends additional commands to a location provider.
open Unit
setTestProviderEnabled(provider: String, enabled: Boolean)

Sets the given test provider to be enabled or disabled.
open Unit
setTestProviderLocation(provider: String, location: Location)

Sets a new location for the given test provider.
open Unit
setTestProviderStatus(provider: String, status: Int, extras: Bundle?, updateTime: Long)

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

Unregisters a GNSS antenna info listener.
open Unit

Unregisters a GPS Measurement callback.
open Unit

Unregisters a GNSS Navigation Message callback.
open Unit

Removes a GNSS status callback.

Constants

ACTION_GNSS_CAPABILITIES_CHANGED

Added in API level 31
static val ACTION_GNSS_CAPABILITIES_CHANGED: String

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, with the new GnssCapabilities.

Value: "android.location.action.GNSS_CAPABILITIES_CHANGED"

EXTRA_GNSS_CAPABILITIES

Added in API level 31
static val EXTRA_GNSS_CAPABILITIES: String

Intent extra included with ACTION_GNSS_CAPABILITIES_CHANGED broadcasts, containing the new GnssCapabilities.

Value: "android.location.extra.GNSS_CAPABILITIES"

EXTRA_LOCATION_ENABLED

Added in API level 30
static val EXTRA_LOCATION_ENABLED: String

Intent extra included with MODE_CHANGED_ACTION broadcasts, containing the boolean enabled state of location.

Value: "android.location.extra.LOCATION_ENABLED"

EXTRA_PROVIDER_ENABLED

Added in API level 30
static val EXTRA_PROVIDER_ENABLED: String

Intent extra included with PROVIDERS_CHANGED_ACTION broadcasts, containing the boolean enabled state of the location provider that has changed.

Value: "android.location.extra.PROVIDER_ENABLED"

EXTRA_PROVIDER_NAME

Added in API level 29
static val EXTRA_PROVIDER_NAME: String

Intent extra included with PROVIDERS_CHANGED_ACTION broadcasts, containing the name of the location provider that has changed.

Value: "android.location.extra.PROVIDER_NAME"

FUSED_PROVIDER

Added in API level 31
static val FUSED_PROVIDER: String

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.

Value: "fused"

GPS_PROVIDER

Added in API level 1
static val GPS_PROVIDER: String

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

  • satellites - the number of satellites used to derive the fix 
Value: "gps"

KEY_FLUSH_COMPLETE

Added in API level 31
static val KEY_FLUSH_COMPLETE: String

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

Value: "flushComplete"

KEY_LOCATIONS

Added in API level 31
static val KEY_LOCATIONS: String

Key used for an extra holding a array of Locations 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 will be present. Use Intent.getParcelableArrayExtra(String) 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).

Value: "locations"

KEY_LOCATION_CHANGED

Added in API level 3
static val KEY_LOCATION_CHANGED: String

Key used for an extra holding a Location value when a location change is sent using a PendingIntent. If the location change includes a list of batched locations via KEY_LOCATIONS then this key will still be present, and will hold the last location in the batch. Use Intent.getParcelableExtra(String) to retrieve the location.

Value: "location"

KEY_PROVIDER_ENABLED

Added in API level 3
static val KEY_PROVIDER_ENABLED: String

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

Value: "providerEnabled"

KEY_PROXIMITY_ENTERING

Added in API level 1
static val KEY_PROXIMITY_ENTERING: String

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

Value: "entering"

KEY_STATUS_CHANGED

Added in API level 3
Deprecated in API level 29
static val KEY_STATUS_CHANGED: String

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

Value: "status"

MODE_CHANGED_ACTION

Added in API level 19
static val MODE_CHANGED_ACTION: String

Broadcast intent action when the device location enabled state changes. From Android R and above, will include a boolean intent extra, EXTRA_LOCATION_ENABLED, with the enabled state of location.

Value: "android.location.MODE_CHANGED"

NETWORK_PROVIDER

Added in API level 1
static val NETWORK_PROVIDER: String

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.

Value: "network"

PASSIVE_PROVIDER

Added in API level 8
static val PASSIVE_PROVIDER: String

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.

Value: "passive"

PROVIDERS_CHANGED_ACTION

Added in API level 9
static val PROVIDERS_CHANGED_ACTION: String

Broadcast intent action when the set of enabled location providers changes. To check the status of a provider, use isProviderEnabled(java.lang.String). From Android Q and above, will include a string intent extra, EXTRA_PROVIDER_NAME, with the name of the provider whose state has changed. From Android R and above, will include a boolean intent extra, EXTRA_PROVIDER_ENABLED, with the enabled state of the provider.

Value: "android.location.PROVIDERS_CHANGED"

Public methods

addGpsStatusListener

Added in API level 3
Deprecated in API level 24
open fun addGpsStatusListener(listener: GpsStatus.Listener!): Boolean

Deprecated: Use registerGnssStatusCallback(android.location.GnssStatus.Callback,android.os.Handler) or registerGnssStatusCallback(java.util.concurrent.Executor,android.location.GnssStatus.Callback) instead.

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

Parameters
listener GpsStatus.Listener!: GPS status listener object to register
Return
Boolean true if the listener was successfully added
Exceptions
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

addNmeaListener

Added in API level 5
Deprecated in API level 24
open fun addNmeaListener(listener: GpsStatus.NmeaListener): Boolean

Deprecated: Use addNmeaListener(android.location.OnNmeaMessageListener,android.os.Handler) or addNmeaListener(java.util.concurrent.Executor,android.location.OnNmeaMessageListener) instead.

No-op method to keep backward-compatibility.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
listener GpsStatus.NmeaListener: This value cannot be null.

addNmeaListener

Added in API level 24
Deprecated in API level 30
open fun addNmeaListener(listener: OnNmeaMessageListener): Boolean

Deprecated: Use addNmeaListener(android.location.OnNmeaMessageListener,android.os.Handler) or addNmeaListener(java.util.concurrent.Executor,android.location.OnNmeaMessageListener) instead.

Adds an NMEA listener.

See addNmeaListener(java.util.concurrent.Executor,android.location.OnNmeaMessageListener) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
listener OnNmeaMessageListener: the listener to register This value cannot be null.
Return
Boolean true always
Exceptions
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

addNmeaListener

Added in API level 24
open fun addNmeaListener(
    listener: OnNmeaMessageListener, 
    handler: Handler?
): Boolean

Adds an NMEA listener.

See addNmeaListener(java.util.concurrent.Executor,android.location.OnNmeaMessageListener) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
listener OnNmeaMessageListener: the listener to register This value cannot be null.
handler Handler?: the handler that the listener runs on This value may be null.
Return
Boolean true always
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

addNmeaListener

Added in API level 30
open fun addNmeaListener(
    executor: Executor, 
    listener: OnNmeaMessageListener
): Boolean

Adds an NMEA listener. GNSS NMEA information will only be received while the GPS_PROVIDER is enabled, and while the client app is in the foreground.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

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

addProximityAlert

Added in API level 1
open fun addProximityAlert(
    latitude: Double, 
    longitude: Double, 
    radius: Float, 
    expiration: Long, 
    pendingIntent: PendingIntent
): Unit

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. 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 android.Manifest.permission#ACCESS_FINE_LOCATION or android.Manifest.permission#ACCESS_COARSE_LOCATION. From API version 17 and onwards, this method requires android.Manifest.permission#ACCESS_FINE_LOCATION permission.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.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: 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.
Exceptions
java.lang.SecurityException if android.Manifest.permission#ACCESS_FINE_LOCATION permission is not present

addTestProvider

Added in API level 31
open fun addTestProvider(
    provider: String, 
    properties: ProviderProperties
): Unit

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: This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if properties is null
java.lang.SecurityException if mock location app op is not set to allowed for your app.

addTestProvider

Added in API level 31
open fun addTestProvider(
    provider: String, 
    properties: ProviderProperties, 
    extraAttributionTags: MutableSet<String!>
): Unit

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 MutableSet<String!>: additional attribution tags associated with this provider This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if properties is null
java.lang.SecurityException if mock location app op is not set to allowed for your app.

addTestProvider

Added in API level 3
open fun addTestProvider(
    provider: String, 
    requiresNetwork: Boolean, 
    requiresSatellite: Boolean, 
    requiresCell: Boolean, 
    hasMonetaryCost: Boolean, 
    supportsAltitude: Boolean, 
    supportsSpeed: Boolean, 
    supportsBearing: Boolean, 
    powerUsage: Int, 
    accuracy: Int
): Unit

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.
powerUsage Int: Value is android.location.provider.ProviderProperties#POWER_USAGE_LOW, android.location.provider.ProviderProperties#POWER_USAGE_MEDIUM, or android.location.provider.ProviderProperties#POWER_USAGE_HIGH
accuracy Int: Value is android.location.provider.ProviderProperties#ACCURACY_FINE, or android.location.provider.ProviderProperties#ACCURACY_COARSE
Exceptions
java.lang.IllegalArgumentException if provider is null
java.lang.SecurityException if mock location app op is not set to allowed for your app.

clearTestProviderEnabled

Added in API level 3
Deprecated in API level 29
open fun clearTestProviderEnabled(provider: String): Unit

Deprecated: Use setTestProviderEnabled(java.lang.String,boolean) instead.

Equivalent to calling setTestProviderEnabled(java.lang.String,boolean) to disable a test provider.

Parameters
provider String: This value cannot be null.

clearTestProviderLocation

Added in API level 3
Deprecated in API level 29
open fun clearTestProviderLocation(provider: String): Unit

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

Added in API level 3
Deprecated in API level 29
open fun clearTestProviderStatus(provider: String): Unit

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

Added in API level 1
open fun getAllProviders(): MutableList<String!>

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

Return
MutableList<String!> list of provider names This value cannot be null.

getBestProvider

Added in API level 1
Deprecated in API level 34
open fun getBestProvider(
    criteria: Criteria, 
    enabledOnly: Boolean
): String?

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

  • 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 This value cannot be null.
enabledOnly Boolean: if true then only enabled providers are included
Return
String? name of the provider that best matches the criteria, or null if none match
Exceptions
java.lang.IllegalArgumentException if criteria is null

getCurrentLocation

Added in API level 31
open fun getCurrentLocation(
    provider: String, 
    locationRequest: LocationRequest, 
    cancellationSignal: CancellationSignal?, 
    executor: Executor, 
    consumer: Consumer<Location!>
): Unit

Asynchronously returns a single current location fix from the given provider based on the given LocationRequest. This may activate sensors in order to compute a new location, unlike getLastKnownLocation(java.lang.String), 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. 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() 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 android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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 this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
consumer Consumer<Location!>: the callback invoked with either a Location or null
Exceptions
java.lang.IllegalArgumentException if consumer is null
java.lang.SecurityException if no suitable permission is present

getCurrentLocation

Added in API level 30
open fun getCurrentLocation(
    provider: String, 
    cancellationSignal: CancellationSignal?, 
    executor: Executor, 
    consumer: Consumer<Location!>
): Unit

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

See getCurrentLocation(java.lang.String,android.location.LocationRequest,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) for more information.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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 this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
consumer Consumer<Location!>: the callback invoked with either a Location or null
Exceptions
java.lang.IllegalArgumentException if consumer is null
java.lang.SecurityException if no suitable permission is present

getGnssAntennaInfos

Added in API level 31
open fun getGnssAntennaInfos(): MutableList<GnssAntennaInfo!>?

Returns the current list of GNSS antenna infos, or null if unknown or unsupported.

getGnssCapabilities

Added in API level 30
open fun getGnssCapabilities(): GnssCapabilities

Returns the supported capabilities of the GNSS chipset.

Return
GnssCapabilities This value cannot be null.

getGnssHardwareModelName

Added in API level 28
open fun getGnssHardwareModelName(): String?

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.

getGnssYearOfHardware

Added in API level 28
open fun getGnssYearOfHardware(): Int

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

getGpsStatus

Added in API level 3
Deprecated in API level 24
open fun getGpsStatus(status: GpsStatus?): GpsStatus?

Deprecated: GpsStatus APIs are deprecated, use 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 callback to ensure that the data is copied atomically. The caller may either pass in an existing GpsStatus object to be overwritten, or pass null to create a new GpsStatus object.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

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

getLastKnownLocation

Added in API level 1
open fun getLastKnownLocation(provider: String): Location?

Gets the last known location from the given provider, or null if there is no last known location. The returned location may be quite old in some circumstances, so the age of the location should always be checked.

This will never activate sensors to compute a new location, and will only ever return a cached location.

See also getCurrentLocation(java.lang.String,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) which will always attempt to return a current location, but will potentially use additional power in the course of the attempt as compared to this method.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
Return
Location? the last known location for the given provider, or null if not available
Exceptions
java.lang.SecurityException if no suitable permission is present
java.lang.IllegalArgumentException if provider is null or doesn't exist

getProvider

Added in API level 1
Deprecated in API level 31
open fun getProvider(provider: String): LocationProvider?

Deprecated: 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(java.lang.String) 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.
Return
LocationProvider? location provider information, or null if provider does not exist
Exceptions
java.lang.IllegalArgumentException if provider is null

getProviderProperties

Added in API level 31
open fun getProviderProperties(provider: String): ProviderProperties?

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.
Return
ProviderProperties? location provider properties, or null if properties are currently unknown
Exceptions
java.lang.IllegalArgumentException if provider is null or does not exist

getProviders

Added in API level 1
Deprecated in API level 34
open fun getProviders(
    criteria: Criteria, 
    enabledOnly: Boolean
): MutableList<String!>

Deprecated: 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
Return
MutableList<String!> list of provider names This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if criteria is null

getProviders

Added in API level 1
open fun getProviders(enabledOnly: Boolean): MutableList<String!>

Returns a list of the names of available location providers. If enabledOnly is false, this is functionally the same as getAllProviders().

Parameters
enabledOnly Boolean: if true then only enabled providers are included
Return
MutableList<String!> list of provider names This value cannot be null.

hasProvider

Added in API level 31
open fun hasProvider(provider: String): Boolean

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.
Return
Boolean true if the location provider exists, false otherwise
Exceptions
java.lang.IllegalArgumentException if provider is null

isLocationEnabled

Added in API level 28
open fun isLocationEnabled(): Boolean

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

Return
Boolean true if location is enabled and false if location is disabled.

isProviderEnabled

Added in API level 1
open fun isProviderEnabled(provider: String): Boolean

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

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
Return
Boolean true if the provider exists and is enabled
Exceptions
java.lang.IllegalArgumentException if provider is null

registerAntennaInfoListener

Added in API level 30
open fun registerAntennaInfoListener(
    executor: Executor, 
    listener: GnssAntennaInfo.Listener
): Boolean

Registers a GNSS antenna info listener that will receive all changes to antenna info. Use getGnssAntennaInfos() to get current antenna info.

Not all GNSS chipsets support antenna info updates, see getGnssCapabilities(). If unsupported, the listener will never be invoked.

Prior to Android S, this requires the Manifest.permission.ACCESS_FINE_LOCATION permission.

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

registerGnssMeasurementsCallback

Added in API level 31
open fun registerGnssMeasurementsCallback(
    request: GnssMeasurementRequest, 
    executor: Executor, 
    callback: GnssMeasurementsEvent.Callback
): Boolean

Registers a GNSS measurement callback.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
request GnssMeasurementRequest: extra parameters to pass to GNSS measurement provider. For example, if android.location.GnssMeasurementRequest#isFullTracking() is true, GNSS chipset switches off duty cycling. This value cannot be null.
executor Executor: the executor that the callback runs on This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback GnssMeasurementsEvent.Callback: a GnssMeasurementsEvent.Callback object to register. This value cannot be null.
Return
Boolean true always if the callback was added successfully, false otherwise.
Exceptions
java.lang.IllegalArgumentException if callback is null
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

registerGnssMeasurementsCallback

open fun registerGnssMeasurementsCallback(callback: GnssMeasurementsEvent.Callback): Boolean

Deprecated: Deprecated in Java.

Registers a GNSS measurements callback which will run on a binder thread.

See for more detail on how this method works.

registerGnssMeasurementsCallback

open fun registerGnssMeasurementsCallback(
    callback: GnssMeasurementsEvent.Callback, 
    handler: Handler?
): Boolean

Registers a GNSS measurements callback.

See for more detail on how this method works.

registerGnssMeasurementsCallback

Added in API level 30
open fun registerGnssMeasurementsCallback(
    executor: Executor, 
    callback: GnssMeasurementsEvent.Callback
): Boolean

Registers a GNSS measurements callback. GNSS measurements information will only be received while the GPS_PROVIDER is enabled, and while the client app is in the foreground.

Not all GNSS chipsets support measurements updates, see getGnssCapabilities().

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 use LocationManagerCompat.registerGnssMeasurementsCallback() from the compat libraries instead to avoid this crash.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

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

registerGnssNavigationMessageCallback

Added in API level 24
Deprecated in API level 30
open fun registerGnssNavigationMessageCallback(callback: GnssNavigationMessage.Callback): Boolean

Deprecated: Use registerGnssNavigationMessageCallback(android.location.GnssNavigationMessage.Callback,android.os.Handler) or registerGnssNavigationMessageCallback(java.util.concurrent.Executor,android.location.GnssNavigationMessage.Callback) instead.

Registers a GNSS navigation message callback which will run on a binder thread.

See registerGnssNavigationMessageCallback(java.util.concurrent.Executor,android.location.GnssNavigationMessage.Callback) for more detail on how this method works.

Parameters
callback GnssNavigationMessage.Callback: the callback to register This value cannot be null.
Return
Boolean true always

registerGnssNavigationMessageCallback

Added in API level 24
open fun registerGnssNavigationMessageCallback(
    callback: GnssNavigationMessage.Callback, 
    handler: Handler?
): Boolean

Registers a GNSS navigation message callback.

See registerGnssNavigationMessageCallback(java.util.concurrent.Executor,android.location.GnssNavigationMessage.Callback) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
callback GnssNavigationMessage.Callback: the callback to register This value cannot be null.
handler Handler?: the handler that the callback runs on This value may be null.
Return
Boolean true always
Exceptions
java.lang.IllegalArgumentException if callback is null
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

registerGnssNavigationMessageCallback

Added in API level 30
open fun registerGnssNavigationMessageCallback(
    executor: Executor, 
    callback: GnssNavigationMessage.Callback
): Boolean

Registers a GNSS navigation message callback. GNSS navigation messages will only be received while the GPS_PROVIDER is enabled, and while the client app is in the foreground.

Not all GNSS chipsets support navigation message updates, see getGnssCapabilities().
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

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

registerGnssStatusCallback

Added in API level 24
Deprecated in API level 30
open fun registerGnssStatusCallback(callback: GnssStatus.Callback): Boolean

Deprecated: Use registerGnssStatusCallback(android.location.GnssStatus.Callback,android.os.Handler) or registerGnssStatusCallback(java.util.concurrent.Executor,android.location.GnssStatus.Callback) instead.

Registers a GNSS status callback. This method must be called from a Looper thread, and callbacks will occur on that looper.

See registerGnssStatusCallback(java.util.concurrent.Executor,android.location.GnssStatus.Callback) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
callback GnssStatus.Callback: the callback to register This value cannot be null.
Return
Boolean true always
Exceptions
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

registerGnssStatusCallback

Added in API level 24
open fun registerGnssStatusCallback(
    callback: GnssStatus.Callback, 
    handler: Handler?
): Boolean

Registers a GNSS status callback.

See registerGnssStatusCallback(java.util.concurrent.Executor,android.location.GnssStatus.Callback) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
callback GnssStatus.Callback: the callback to register This value cannot be null.
handler Handler?: the handler the callback runs on This value may be null.
Return
Boolean true always
Exceptions
java.lang.IllegalArgumentException if callback is null
java.lang.SecurityException if the ACCESS_FINE_LOCATION permission is not present

registerGnssStatusCallback

Added in API level 30
open fun registerGnssStatusCallback(
    executor: Executor, 
    callback: GnssStatus.Callback
): Boolean

Registers a GNSS status callback. GNSS status information will only be received while the GPS_PROVIDER is enabled, and while the client app is in the foreground.
Requires android.Manifest.permission#ACCESS_FINE_LOCATION

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

removeGpsStatusListener

Added in API level 3
Deprecated in API level 24
open fun removeGpsStatusListener(listener: GpsStatus.Listener!): Unit

Deprecated: use unregisterGnssStatusCallback(android.location.GnssStatus.Callback) 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

Added in API level 5
Deprecated in API level 24
open fun removeNmeaListener(listener: GpsStatus.NmeaListener): Unit

Deprecated: Use removeNmeaListener(android.location.OnNmeaMessageListener) instead.

No-op method to keep backward-compatibility.

Parameters
listener GpsStatus.NmeaListener: This value cannot be null.

removeNmeaListener

Added in API level 24
open fun removeNmeaListener(listener: OnNmeaMessageListener): Unit

Removes an NMEA listener.

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

removeProximityAlert

Added in API level 1
open fun removeProximityAlert(intent: PendingIntent): Unit

Removes the proximity alert with the given PendingIntent.

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

Parameters
intent PendingIntent: the PendingIntent that no longer needs to be notified of proximity alerts This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if intent is null
java.lang.SecurityException if android.Manifest.permission#ACCESS_FINE_LOCATION permission is not present

removeTestProvider

Added in API level 3
open fun removeTestProvider(provider: String): Unit

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.
Exceptions
java.lang.IllegalArgumentException if provider is null
java.lang.SecurityException if mock location app op is not set to allowed for your app.

removeUpdates

Added in API level 3
open fun removeUpdates(pendingIntent: PendingIntent): Unit

Removes location updates for the specified PendingIntent. Following this call, the PendingIntent will no longer receive location updates.

See removeUpdates(android.location.LocationListener) for more detail on how this method works.

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

removeUpdates

Added in API level 1
open fun removeUpdates(listener: LocationListener): Unit

Removes all location updates for the specified LocationListener. The given listener is guaranteed not to receive any invocations that happens-after this method is invoked.

If the given listener has any batched requests, this method will not flush any incomplete location batches before stopping location updates. If you wish to flush any pending locations before stopping, you must first call requestFlush(java.lang.String,android.location.LocationListener,int) and then call this method once the flush is complete. If this method is invoked before the flush is complete, you may not receive the flushed locations.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

Parameters
listener LocationListener: listener that no longer needs location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if listener is null

requestFlush

Added in API level 31
open fun requestFlush(
    provider: String, 
    pendingIntent: PendingIntent, 
    requestCode: Int
): Unit

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 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 for KEY_FLUSH_COMPLETE
Exceptions
java.lang.IllegalArgumentException if pending intent is null or is not registered under the provider

requestFlush

Added in API level 31
open fun requestFlush(
    provider: String, 
    listener: LocationListener, 
    requestCode: Int
): Unit

Requests that the given provider flush any batched locations to listeners. The given listener (registered with the provider) will have LocationListener.onFlushComplete(int) invoked with the given result code after any locations that were flushed have been delivered. If removeUpdates(android.location.LocationListener) is invoked before the flush callback is executed, then the flush callback will never be executed.

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
listener LocationListener: a listener registered under the provider This value cannot be null.
requestCode Int: an arbitrary integer passed through to LocationListener.onFlushComplete(int)
Exceptions
java.lang.IllegalArgumentException if listener is null or is not registered under the provider

requestLocationUpdates

Added in API level 31
open fun requestLocationUpdates(
    provider: String, 
    locationRequest: LocationRequest, 
    pendingIntent: PendingIntent
): Unit

Register for location updates from the specified provider, using a LocationRequest, and callbacks delivered via the provided PendingIntent.

The delivered pending intents will contain extras with the callback information. The keys used for the extras are KEY_LOCATION_CHANGED and KEY_PROVIDER_ENABLED. See the documentation for each respective extra key for information on the values.

To unregister for location updates, use removeUpdates(android.app.PendingIntent).
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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.
pendingIntent PendingIntent: the pending intent to send location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if pendingIntent is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 31
open fun requestLocationUpdates(
    provider: String, 
    locationRequest: LocationRequest, 
    executor: Executor, 
    listener: LocationListener
): Unit

Register for location updates from the specified provider, using a LocationRequest, and a callback on the specified 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(java.lang.String) or getCurrentLocation(java.lang.String,android.location.LocationRequest,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) instead.

See 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. 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 are with respect to the primary GNSS antenna position within the device. getGnssAntennaInfos() 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(android.location.LocationListener).
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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 this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener LocationListener: the listener to receive location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 3
open fun requestLocationUpdates(
    provider: String, 
    minTimeMs: Long, 
    minDistanceM: Float, 
    pendingIntent: PendingIntent
): Unit

Register for location updates using the named provider, and callbacks delivered via the provided PendingIntent.

See requestLocationUpdates(java.lang.String,android.location.LocationRequest,android.app.PendingIntent) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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
pendingIntent PendingIntent: the pending intent to send location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if pendingIntent is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 1
open fun requestLocationUpdates(
    provider: String, 
    minTimeMs: Long, 
    minDistanceM: Float, 
    listener: LocationListener
): Unit

Register for location updates from the given provider with the given arguments, and a callback on the Looper of the calling thread.

See requestLocationUpdates(java.lang.String,android.location.LocationRequest,java.util.concurrent.Executor,android.location.LocationListener) 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 android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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.
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.RuntimeException if the calling thread has no Looper
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 1
open fun requestLocationUpdates(
    provider: String, 
    minTimeMs: Long, 
    minDistanceM: Float, 
    listener: LocationListener, 
    looper: Looper?
): Unit

Register for location updates from the given provider with the given arguments, and a callback on the specified Looper.

See requestLocationUpdates(java.lang.String,android.location.LocationRequest,java.util.concurrent.Executor,android.location.LocationListener) 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 android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 30
open fun requestLocationUpdates(
    provider: String, 
    minTimeMs: Long, 
    minDistanceM: Float, 
    executor: Executor, 
    listener: LocationListener
): Unit

Register for location updates using the named provider, and a callback on the specified Executor.

See requestLocationUpdates(java.lang.String,android.location.LocationRequest,java.util.concurrent.Executor,android.location.LocationListener) 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 android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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 this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener LocationListener: the listener to receive location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 9
Deprecated in API level 31
open fun requestLocationUpdates(
    minTimeMs: Long, 
    minDistanceM: Float, 
    criteria: Criteria, 
    pendingIntent: PendingIntent
): Unit

Deprecated: Use requestLocationUpdates(java.lang.String,long,float,android.app.PendingIntent) 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.

Note: Since Android KitKat, Criteria requests will always result in using the FUSED_PROVIDER.

See requestLocationUpdates(java.lang.String,long,float,android.app.PendingIntent) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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.
Exceptions
java.lang.IllegalArgumentException if pendingIntent is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 9
Deprecated in API level 31
open fun requestLocationUpdates(
    minTimeMs: Long, 
    minDistanceM: Float, 
    criteria: Criteria, 
    listener: LocationListener, 
    looper: Looper?
): Unit

Deprecated: Use requestLocationUpdates(java.lang.String,long,float,android.location.LocationListener,android.os.Looper) 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.

Note: Since Android KitKat, Criteria requests will always result in using the FUSED_PROVIDER.

See requestLocationUpdates(java.lang.String,android.location.LocationRequest,java.util.concurrent.Executor,android.location.LocationListener) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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.
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

requestLocationUpdates

Added in API level 30
Deprecated in API level 31
open fun requestLocationUpdates(
    minTimeMs: Long, 
    minDistanceM: Float, 
    criteria: Criteria, 
    executor: Executor, 
    listener: LocationListener
): Unit

Deprecated: Use requestLocationUpdates(java.lang.String,long,float,java.util.concurrent.Executor,android.location.LocationListener) 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.

Note: Since Android KitKat, Criteria requests will always result in using the FUSED_PROVIDER.

See requestLocationUpdates(java.lang.String,android.location.LocationRequest,java.util.concurrent.Executor,android.location.LocationListener) for more detail on how this method works.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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 this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
listener LocationListener: the listener to receive location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

requestSingleUpdate

Added in API level 9
Deprecated in API level 30
open fun requestSingleUpdate(
    criteria: Criteria, 
    pendingIntent: PendingIntent
): Unit

Deprecated: Use getCurrentLocation(java.lang.String,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) instead as it does not carry a risk of extreme battery drain.

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

Note: Since Android KitKat, Criteria requests will always result in using the FUSED_PROVIDER.

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

Parameters
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.
Exceptions
java.lang.IllegalArgumentException if intent is null
java.lang.SecurityException if no suitable permission is present

requestSingleUpdate

Added in API level 9
Deprecated in API level 30
open fun requestSingleUpdate(
    criteria: Criteria, 
    listener: LocationListener, 
    looper: Looper?
): Unit

Deprecated: Use getCurrentLocation(java.lang.String,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) 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.

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

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
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

requestSingleUpdate

Added in API level 9
Deprecated in API level 30
open fun requestSingleUpdate(
    provider: String, 
    pendingIntent: PendingIntent
): Unit

Deprecated: Use getCurrentLocation(java.lang.String,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) instead as it does not carry a risk of extreme battery drain.

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

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

Parameters
provider String: a provider listed by getAllProviders() This value cannot be null.
pendingIntent PendingIntent: the pending intent to send location updates This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if intent is null
java.lang.SecurityException if no suitable permission is present

requestSingleUpdate

Added in API level 9
Deprecated in API level 30
open fun requestSingleUpdate(
    provider: String, 
    listener: LocationListener, 
    looper: Looper?
): Unit

Deprecated: Use getCurrentLocation(java.lang.String,android.os.CancellationSignal,java.util.concurrent.Executor,java.util.function.Consumer) 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(java.lang.String,long,float,android.location.LocationListener,android.os.Looper) for more detail on how to use this method.
Requires android.Manifest.permission#ACCESS_COARSE_LOCATION or android.Manifest.permission#ACCESS_FINE_LOCATION

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
Exceptions
java.lang.IllegalArgumentException if listener is null
java.lang.SecurityException if no suitable permission is present

sendExtraCommand

Added in API level 3
open fun sendExtraCommand(
    provider: String, 
    command: String, 
    extras: Bundle?
): Boolean

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
Return
Boolean true always, the return value may be ignored

setTestProviderEnabled

Added in API level 3
open fun setTestProviderEnabled(
    provider: String, 
    enabled: Boolean
): Unit

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
Exceptions
java.lang.SecurityException if mock location app op is not set to allowed for your app.
java.lang.IllegalArgumentException if provider is null or not a test provider

setTestProviderLocation

Added in API level 3
open fun setTestProviderLocation(
    provider: String, 
    location: Location
): Unit

Sets a new location for the given test provider. This location will be identiable as a mock location to all clients via Location.isMock().

The location object must have a minimum number of fields set to be considered valid, as per documentation on Location class.

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

setTestProviderStatus

Added in API level 3
Deprecated in API level 29
open fun setTestProviderStatus(
    provider: String, 
    status: Int, 
    extras: Bundle?, 
    updateTime: Long
): Unit

Deprecated: 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.
extras Bundle?: This value may be null.

unregisterAntennaInfoListener

Added in API level 30
open fun unregisterAntennaInfoListener(listener: GnssAntennaInfo.Listener): Unit

Unregisters a GNSS antenna info listener.

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

unregisterGnssMeasurementsCallback

Added in API level 24
open fun unregisterGnssMeasurementsCallback(callback: GnssMeasurementsEvent.Callback): Unit

Unregisters a GPS Measurement callback.

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

unregisterGnssNavigationMessageCallback

Added in API level 24
open fun unregisterGnssNavigationMessageCallback(callback: GnssNavigationMessage.Callback): Unit

Unregisters a GNSS Navigation Message callback.

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

unregisterGnssStatusCallback

Added in API level 24
open fun unregisterGnssStatusCallback(callback: GnssStatus.Callback): Unit

Removes a GNSS status callback.

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