public class

FusedLocationProviderClient

extends GoogleApi<Api.ApiOptions.NoOptions>
java.lang.Object
   ↳ com.google.android.gms.common.api.GoogleApi<com.google.android.gms.common.api.Api.ApiOptions.NoOptions>
     ↳ com.google.android.gms.location.FusedLocationProviderClient

Class Overview

The main entry point for interacting with the fused location provider.

Summary

Public Methods
Task<Void> flushLocations()
Flushes any locations currently being batched and sends them to all registered LocationListeners, LocationCallbacks, and PendingIntents.
Task<Location> getLastLocation()
Returns the best most recent location currently available.
Task<LocationAvailability> getLocationAvailability()
Returns the availability of location data.
Task<Void> removeLocationUpdates(PendingIntent callbackIntent)
Removes all location updates for the given pending intent.
Task<Void> removeLocationUpdates(LocationCallback callback)
Removes all location updates for the given location result listener.
Task<Void> requestLocationUpdates(LocationRequest request, LocationCallback callback, Looper looper)
Requests location updates with a callback on the specified Looper thread.
Task<Void> requestLocationUpdates(LocationRequest request, PendingIntent callbackIntent)
Requests location updates with a callback on the specified PendingIntent.
Task<Void> setMockLocation(Location mockLocation)
Sets the mock location to be used for the location provider.
Task<Void> setMockMode(boolean isMockMode)
Sets whether or not the location provider is in mock mode.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public Task<Void> flushLocations ()

Flushes any locations currently being batched and sends them to all registered LocationListeners, LocationCallbacks, and PendingIntents. This call is only useful when batching is specified using setMaxWaitTime(long), otherwise locations are already delivered immediately when available.

When the returned Task is complete, then you can assume that any pending batched locations have already been delivered.

Returns
Task<Void>

public Task<Location> getLastLocation ()

Returns the best most recent location currently available.

If a location is not available, which should happen very rarely, null will be returned. The best accuracy available while respecting the location permissions will be returned.

This method provides a simplified way to get location. It is particularly well suited for applications that do not require an accurate location and that do not want to maintain extra logic for location updates.

Returns
Task<Location>

public Task<LocationAvailability> getLocationAvailability ()

Returns the availability of location data. When isLocationAvailable() returns true, then the location returned by getLastLocation() will be reasonably up to date within the hints specified by the active LocationRequests.

If the client isn't connected to Google Play services and the request times out, null is returned.

Note it's always possible for getLastLocation() to return null even when this method returns true (e.g. location settings were disabled between calls).

Returns
Task<LocationAvailability>

public Task<Void> removeLocationUpdates (PendingIntent callbackIntent)

Removes all location updates for the given pending intent.

It is possible for this call to cancel the PendingIntent under some circumstances.

Parameters
callbackIntent PendingIntent: The PendingIntent that was used in requestLocationUpdates(LocationRequest, PendingIntent) or is equal as defined by equals(Object).
Returns
Task<Void> a Task for the call, check isSuccessful() to determine if it was successful.

public Task<Void> removeLocationUpdates (LocationCallback callback)

Removes all location updates for the given location result listener.

Parameters
callback LocationCallback: The callback to remove.
Returns
Task<Void> a Task for the call, check isSuccessful() to determine if it was successful.

public Task<Void> requestLocationUpdates (LocationRequest request, LocationCallback callback, Looper looper)

Requests location updates with a callback on the specified Looper thread.

This method is suited for the foreground use cases. For background use cases, the PendingIntent version of the method is recommended, see requestLocationUpdates(LocationRequest, PendingIntent).

Any previous LocationRequests registered on this LocationListener will be replaced.

This call will keep the Google Play services connection active, so make sure to call removeLocationUpdates(LocationCallback) when you no longer need it, otherwise you lose the benefits of the automatic connection management.

Callbacks for LocationCallback will be made on the specified thread, which must already be a prepared looper thread.

Parameters
request LocationRequest: The location request for the updates.
callback LocationCallback: The callback for the location updates.
looper Looper: The Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on the calling thread.
Returns
Task<Void> a Task for the call, check isSuccessful() to determine if it was successful.
Throws
IllegalStateException If looper is null and this method is executed in a thread that has not called Looper.prepare().

public Task<Void> requestLocationUpdates (LocationRequest request, PendingIntent callbackIntent)

Requests location updates with a callback on the specified PendingIntent.

This method is suited for the background use cases, more specifically for receiving location updates, even when the app has been killed by the system. In order to do so, use a PendingIntent for a started service. For foreground use cases, the LocationCallback version of the method is recommended, see requestLocationUpdates(LocationRequest, LocationCallback, Looper).

Any previously registered requests that have the same PendingIntent (as defined by equals(Object)) will be replaced by this request.

Both LocationResult and LocationAvailability are sent to the given PendingIntent. You can extract data from an Intent using hasResult(Intent), extractResult(Intent), hasLocationAvailability(Intent), and extractLocationAvailability(Intent).

Parameters
request LocationRequest: The location request for the updates.
callbackIntent PendingIntent: A pending intent to be sent for each location update.
Returns
Task<Void> a Task for the call, check isSuccessful() to determine if it was successful.

public Task<Void> setMockLocation (Location mockLocation)

Sets the mock location to be used for the location provider. This location will be used in place of any actual locations from the underlying providers (network or gps).

setMockMode(boolean) must be called and set to true prior to calling this method.

Care should be taken in specifying the timestamps as many applications require them to be monotonically increasing.

Parameters
mockLocation Location: The mock location. Must have a minimum number of fields set to be considered a valild location, as per documentation in the Location class.
Returns
Task<Void> a Task for the call, check isSuccessful() to determine if it was successful.
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled.

public Task<Void> setMockMode (boolean isMockMode)

Sets whether or not the location provider is in mock mode.

The underlying providers (network and gps) will be stopped (except by direct LocationManager access), and only locations specified in setMockLocation(Location) will be reported. This will effect all location clients connected using the FusedLocationProviderApi, including geofencer clients (i.e. geofences can be triggered based on mock locations).

The client must remain connected in order for mock mode to remain active. If the client dies the system will return to its normal state.

Calls are not nested, and mock mode will be set directly regardless of previous calls.

Parameters
isMockMode boolean: If true the location provider will be set to mock mode. If false it will be returned to its normal state.
Returns
Task<Void> a Task for the call, check isSuccessful() to determine if it was successful.
Throws
SecurityException if the ACCESS_MOCK_LOCATION permission is not present or the Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled.