FusedLocationProviderClient

public class FusedLocationProviderClient extends GoogleApi<Api.ApiOptions.NoOptions>

The main entry point for interacting with the Fused Location Provider.

Constant Summary

String KEY_MOCK_LOCATION Key used for the Bundle extra in Location object holding a boolean indicating whether the location was set using setMockLocation(Location).
String KEY_VERTICAL_ACCURACY Key used for the Bundle extra in Location object holding a float indicating the estimated vertical accuracy of the location, in meters.

Public Method Summary

Task<Void>
flushLocations()
Flushes any locations currently being batched and sends them to all registered LocationListeners, LocationCallbacks, and PendingIntents.
Task<Location>
getCurrentLocation(int priority, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current location of the device.
Task<Location>
getCurrentLocation(CurrentLocationRequest request, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current location of the device.
Task<Location>
getLastLocation(LastLocationRequest request)
Returns the most recent historical location currently available according to the given request.
Task<Location>
getLastLocation()
Returns the most recent historical location currently available.
Task<LocationAvailability>
getLocationAvailability()
Returns the availability of location data.
Task<Void>
removeLocationUpdates(LocationCallback callback)
Removes all location updates for the given callback.
Task<Void>
removeLocationUpdates(PendingIntent callbackIntent)
Removes all location updates for the given pending intent.
Task<Void>
requestLocationUpdates(LocationRequest request, Executor executor, LocationCallback callback)
Requests location updates with the given request and results delivered to the given callback on the specified Executor.
Task<Void>
requestLocationUpdates(LocationRequest request, LocationCallback callback, Looper looper)
Requests location updates with the given request and results delivered to the given callback on the specified Looper.
Task<Void>
requestLocationUpdates(LocationRequest request, PendingIntent pendingIntent)
Requests location updates with the given request and results delivered via the specified PendingIntent.
Task<Void>
setMockLocation(Location location)
Sets the mock location of the Fused Location Provider.
Task<Void>
setMockMode(boolean mockMode)
Sets whether or not the Fused Location Provider is in mock mode.

Inherited Method Summary

Constants

public static final String KEY_MOCK_LOCATION

Key used for the Bundle extra in Location object holding a boolean indicating whether the location was set using setMockLocation(Location). If the value is false this extra is not set.

Constant Value: "mockLocation"

public static final String KEY_VERTICAL_ACCURACY

Key used for the Bundle extra in Location object holding a float indicating the estimated vertical accuracy of the location, in meters.

We define vertical accuracy at 68% confidence. Specifically, as 1-side of the 2-sided range above and below the estimated altitude reported by Location.getAltitude(), within which there is a 68% probability of finding the true altitude.

In the case where the underlying distribution is assumed Gaussian normal, this would be considered 1 standard deviation.

For example, if Location.getAltitude() returns 150, and this extra returns 20 then there is a 68% probability of the true altitude being between 130 and 170 meters.

If you're targeting Android O+ devices you should use directly Location.hasVerticalAccuracy() and Location.getVerticalAccuracyMeters().

Constant Value: "verticalAccuracy"

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

public Task<Location> getCurrentLocation (int priority, CancellationToken cancellationToken)

Returns a single location fix representing the best estimate of the current location of the device. This may return a cached location if a recent enough location fix exists, or may compute a fresh location. If unable to retrieve a current location fix, null will be returned. Background apps calling this method may be throttled, and thus may be returned null results more often.

Clients may supply an optional CancellationToken which may be used to cancel the request.

Parameters
priority Priority used to obtain location
cancellationToken optional CancellationToken to cancel the request

public Task<Location> getCurrentLocation (CurrentLocationRequest request, CancellationToken cancellationToken)

Returns a single location fix representing the best estimate of the current location of the device. This may return a historical location if a recent enough location fix exists, or may compute a fresh location. If unable to retrieve a current location fix, null will be returned. Background apps calling this method may be throttled, and thus may be returned null results more often.

Clients may supply an optional CancellationToken which may be used to cancel the request.

Parameters
request CurrentLocationRequest with parameters detailing how to obtain the current location
cancellationToken optional CancellationToken to cancel the request

public Task<Location> getLastLocation (LastLocationRequest request)

Returns the most recent historical location currently available according to the given request. Will return null if no matching historical location is available.

public Task<Location> getLastLocation ()

Returns the most recent historical location currently available. Will return null if no historical location is available. The historical location may be of an arbitrary age, so clients should check how old the location is to see if it suits their purposes.

public Task<LocationAvailability> getLocationAvailability ()

Returns the availability of location data. When LocationAvailability.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).

public Task<Void> removeLocationUpdates (LocationCallback callback)

Removes all location updates for the given callback.

public Task<Void> removeLocationUpdates (PendingIntent callbackIntent)

Removes all location updates for the given pending intent.

public Task<Void> requestLocationUpdates (LocationRequest request, Executor executor, LocationCallback callback)

Requests location updates with the given request and results delivered to the given callback on the specified Executor. A previous request for location updates for the same callback will be replaced by this request. If the location request has a priority higher than Priority.PRIORITY_PASSIVE, a wakelock may be held on the client's behalf while delivering locations. A wakelock will not be held while delivering availability updates.

Use removeLocationUpdates(LocationCallback) to stop location updates once no longer needed.

Depending on the arguments passed in through the LocationRequest, locations from the past may be delivered when the callback is first registered. Clients should ensure they are checking location timestamps appropriately if necessary.

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

Requests location updates with the given request and results delivered to the given callback on the specified Looper. A previous request for location updates for the same callback will be replaced by this request. If the location request has a priority higher than Priority.PRIORITY_PASSIVE, a wakelock may be held on the client's behalf while delivering locations. A wakelock will not be held while delivering availability updates.

Use removeLocationUpdates(LocationCallback) to stop location updates once no longer needed.

Depending on the arguments passed in through the LocationRequest, locations from the past may be delivered when the callback is first registered. Clients should ensure they are checking location timestamps appropriately if necessary.

If the given Looper is null, the Looper associated with the calling thread will be used instead.

Throws
IllegalStateException if looper is null and the calling thread has not called Looper.prepare()

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

Requests location updates with the given request and results delivered via the specified PendingIntent. A previous request for location updates for the same pending intent will be replaced by this request. If the location request has a priority higher than Priority.PRIORITY_PASSIVE, a wakelock may be held on the client's behalf while delivering locations. A wakelock will not be held while delivering availability updates.

Location updates should be extracted from the received Intent via LocationResult.hasResult(Intent) and LocationResult.extractResult(Intent). Availability updates should be extracted from the Intent via LocationAvailability.hasLocationAvailability(Intent) and LocationAvailability.extractLocationAvailability(Intent).

This method is suited for receiving location updates in the background, even when the receiving app may have been killed by the system. Using a PendingIntent allows the target component to be started and receive location updates. For foreground use cases prefer to listen for location updates via a listener or callback instead of a pending intent.

PendingIntent location requests are automatically removed when the client application is reset (for example, when the client application is upgraded, restarted, removed, or force-quit), or if the pending intent is canceled.

Use removeLocationUpdates(PendingIntent) to stop location updates once no longer needed.

Depending on the arguments passed in through the LocationRequest, locations from the past may be delivered when the callback is first registered. Clients should ensure they are checking location timestamps appropriately if necessary.

public Task<Void> setMockLocation (Location location)

Sets the mock location of the Fused Location Provider.

Delivers the given location to the FLP as if it was coming from an underlying location source. Normal FLP logic around receiving and delivering location will generally apply. For this reason the timestamps of the location should be set appropriately, as the FLP may expect monotonically increasing timestamps. When this location is reported to FLP clients it will be marked as a mock location (see Location.isMock() or LocationCompat.isMock() from the compat libraries).

This API can only be successfully used while the FLP is in mock mode. Clients must fulfill the same security requirements as for setMockMode(boolean) as well.

Parameters
location valid location to set as the next FLP location
Throws
SecurityException if security requirements are not met

public Task<Void> setMockMode (boolean mockMode)

Sets whether or not the Fused Location Provider is in mock mode.

Entering mock mode clears the FLP's cached locations, and ensures that the FLP will only report locations set through setMockLocation(Location). Exiting mock mode will clear any mock locations set from the FLP's cache as well. Mock mode affects all location clients using the FLP, including location clients in other processes and derivative APIs such as geofencing and so forth. Because this affects all FLP usage, clients should always ensure they properly set the mock mode to false when finished.

Successfully using this API on devices running Android M+ requires the client to request the android.permission.ACCESS_MOCK_LOCATION permission and to be selected as the mock location app within the device developer settings. Using this API on pre-M devices requires the Settings.Secure.ALLOW_MOCK_LOCATION setting to be enabled.

Parameters
mockMode the mock mode state to set for the Fused Location Provider APIs
Throws
SecurityException if security requirements are not met