LocationRequest

public final class LocationRequest extends Object
implements Parcelable

An encapsulation of various parameters for requesting location through FusedLocationProviderClient.

There are a variety of different situations where various types of applications may want to use different request parameters. For example, clients that are showing the user's location in realtime may consider a Priority.PRIORITY_HIGH_ACCURACY request with a short interval. At the other extreme, a client that wants a negligible power impact while still receiving opportunistic locations could use a Priority.PRIORITY_PASSIVE request so that the client will not trigger any location updates, but can still receive locations updates triggered by other client's location requests. See the documentation around all the various parameters of LocationRequest for more information.

Clients should consider using LocationRequest.Builder.setMinUpdateIntervalMillis(long) to limit the fastest rate at which their location callbacks may be invoked (and thus limit the amount of power usage they may be blamed for).

Clients cannot specify the exact sensors, such as GNSS, that will be used in order to satisfy location requests. In fact, FusedLocationProviderClient may fuse the results from many different sensors into a single location in order to more accurately estimate the device's location.

Location requests from clients with only the Manifest.permission.ACCESS_COARSE_LOCATION permission may be throttled to a slower interval, and the returned location will be obfuscated to only show a coarse level of accuracy. Since on later Android levels a user can force any application to receive only the coarse permissions, applications should ensure they are testing these scenarios before release as well.

Many location requests parameters are considered hints or best-effort only, and you may receive locations that are more/less accurate and faster/slower than expected.

Location requests that do not specify batching (see isBatched()) are guaranteed to receive locations that are monotonically increasing in time (they will never receive a location that appears to travel backwards in time compared to the prior location). Location requests that allow for batching are guaranteed that every location within a batch is monotonically increasing in time, but may receive out-of-order locations across different batches, and must be prepared to handle such locations correctly for their own needs.

Nested Class Summary

class LocationRequest.Builder Builder for LocationRequest

Constant Summary

int PRIORITY_BALANCED_POWER_ACCURACY This constant is deprecated. Use Priority.PRIORITY_BALANCED_POWER_ACCURACY instead.
int PRIORITY_HIGH_ACCURACY This constant is deprecated. Use Priority.PRIORITY_HIGH_ACCURACY instead.
int PRIORITY_LOW_POWER This constant is deprecated. Use Priority.PRIORITY_LOW_POWER instead.
int PRIORITY_NO_POWER This constant is deprecated. Use Priority.PRIORITY_PASSIVE instead.

Inherited Constant Summary

Field Summary

public static final Creator<LocationRequest> CREATOR

Public Method Summary

static LocationRequest
create()
This method is deprecated. Use LocationRequest.Builder instead. May be removed in a future release.
boolean
equals(Object object)
long
getDurationMillis()
The duration of this request.
long
getExpirationTime()
This method is deprecated. Use getDurationMillis() instead. Using this method will return the duration added to the current elapsed realtime, which may give unexpected results. May be removed in a future release.
long
getFastestInterval()
This method is deprecated. Use getMinUpdateIntervalMillis() instead. May be removed in a future release.
int
getGranularity()
The Granularity of locations returned for this request.
long
getInterval()
This method is deprecated. Use getIntervalMillis() instead. May be removed in a future release.
long
getIntervalMillis()
The desired interval of location updates.
long
getMaxUpdateAgeMillis()
The maximum age of an initial historical location delivered for this request.
long
getMaxUpdateDelayMillis()
The longest a location update may be delayed.
int
getMaxUpdates()
The maximum number of updates delivered to this request.
long
getMaxWaitTime()
This method is deprecated. Use getMaxUpdateDelayMillis() instead. May be removed in a future release.
float
getMinUpdateDistanceMeters()
The minimum distance required between consecutive location updates.
long
getMinUpdateIntervalMillis()
The fastest allowed interval of location updates.
int
getNumUpdates()
This method is deprecated. Use getMaxUpdates() instead. May be removed in a future release.
int
getPriority()
The Priority of the location request.
float
getSmallestDisplacement()
This method is deprecated. Use getMinUpdateDistanceMeters() instead.
int
boolean
isBatched()
True if this request allows batching (i.e.
boolean
isFastestIntervalExplicitlySet()
This method is deprecated. Do not use. May be removed in a future release.
boolean
isPassive()
True if the priority is Priority.PRIORITY_PASSIVE.
boolean
isWaitForAccurateLocation()
If this request is Priority.PRIORITY_HIGH_ACCURACY, this will delay delivery of initial low accuracy locations for a small amount of time in case a high accuracy location can be delivered instead.
LocationRequest
setExpirationDuration(long durationMillis)
This method is deprecated. Use LocationRequest.Builder.setDurationMillis(long) instead. May be removed in a future release.
LocationRequest
setExpirationTime(long elapsedRealtime)
This method is deprecated. Use LocationRequest.Builder.setDurationMillis(long) instead. Using this method will express the expiration time in terms of duration, which may give unexpected results. May be removed in a future release.
LocationRequest
setFastestInterval(long fastestIntervalMillis)
This method is deprecated. Use LocationRequest.Builder.setMinUpdateIntervalMillis(long) instead. May be removed in a future release.
LocationRequest
setInterval(long intervalMillis)
This method is deprecated. Use LocationRequest.Builder.setIntervalMillis(long) instead. May be removed in a future release.
LocationRequest
setMaxWaitTime(long maxWaitTimeMillis)
This method is deprecated. Use LocationRequest.Builder.setMaxUpdateDelayMillis(long) instead. May be removed in a future release.
LocationRequest
setNumUpdates(int maxUpdates)
This method is deprecated. Use LocationRequest.Builder.setMaxUpdates(int) instead. May be removed in a future release.
LocationRequest
setPriority(int priority)
This method is deprecated. Use LocationRequest.Builder.setPriority(int) instead. May be removed in a future release.
LocationRequest
setSmallestDisplacement(float smallestDisplacementMeters)
This method is deprecated. Use LocationRequest.Builder.setMinUpdateDistanceMeters(float) instead. May be removed in a future release.
LocationRequest
setWaitForAccurateLocation(boolean waitForAccurateLocation)
This method is deprecated. Use LocationRequest.Builder.setWaitForAccurateLocation(boolean) instead. May be removed in a future release.
String
void
writeToParcel(Parcel parcel, int flags)

Inherited Method Summary

Constants

public static final int PRIORITY_BALANCED_POWER_ACCURACY

This constant is deprecated.
Use Priority.PRIORITY_BALANCED_POWER_ACCURACY instead.

Constant Value: 102

public static final int PRIORITY_HIGH_ACCURACY

This constant is deprecated.
Use Priority.PRIORITY_HIGH_ACCURACY instead.

Constant Value: 100

public static final int PRIORITY_LOW_POWER

This constant is deprecated.
Use Priority.PRIORITY_LOW_POWER instead.

Constant Value: 104

public static final int PRIORITY_NO_POWER

This constant is deprecated.
Use Priority.PRIORITY_PASSIVE instead.

Constant Value: 105

Fields

public static final Creator<LocationRequest> CREATOR

Public Methods

public static LocationRequest create ()

This method is deprecated.
Use LocationRequest.Builder instead. May be removed in a future release.

public boolean equals (Object object)

public long getDurationMillis ()

The duration of this request. A location request will not receive any locations after it has expired, and will be removed shortly thereafter. A value of Long.MAX_VALUE implies an infinite duration.

public long getExpirationTime ()

This method is deprecated.
Use getDurationMillis() instead. Using this method will return the duration added to the current elapsed realtime, which may give unexpected results. May be removed in a future release.

public long getFastestInterval ()

This method is deprecated.
Use getMinUpdateIntervalMillis() instead. May be removed in a future release.

public int getGranularity ()

The Granularity of locations returned for this request. This controls whether fine or coarse locations may be returned.

public long getInterval ()

This method is deprecated.
Use getIntervalMillis() instead. May be removed in a future release.

public long getIntervalMillis ()

The desired interval of location updates. Location updates may arrive faster than this interval (but no faster than specified by getMinUpdateIntervalMillis()) or slower than this interval (if the request is being throttled for example).

public long getMaxUpdateAgeMillis ()

The maximum age of an initial historical location delivered for this request. A value of 0 indicates that no initial historical location will be delivered, only freshly derived locations. A value Long.MAX_VALUE represents an effectively unbounded maximum age.

This parameter applies only to a historical location which may be delivered as the very first location for a location request. Subsequent locations will always be freshly derived, and this parameter does not apply to them.

public long getMaxUpdateDelayMillis ()

The longest a location update may be delayed. This parameter controls location batching behavior. If this is set to a value at least 2x larger than the interval specified by getIntervalMillis(), then a device may (but is not required to) save power by delivering locations in batches. If clients do not require immediate delivery, consider setting this value as high as is reasonable to allow for additional power savings.

For example, if a request is made with a 2s interval and a 10s maximum update delay, this implies that the device may choose to deliver batches of 5 locations every 10s (where each location should represent a point in time ~2s after the previous).

Support for batching may vary by device type, so simply allowing batching via this parameter does not imply a client will receive batched results on all devices.

FusedLocationProviderClient.flushLocations() may be used to flush locations that have been batched, but not delivered yet.

Location requests that allow for batching may receive out-of-order locations, and must be prepared to handle such locations correctly for their own needs. See isBatched() for more information.

public int getMaxUpdates ()

The maximum number of updates delivered to this request. A location request will not receive any locations after the maximum number of updates has been reached, and will be removed shortly thereafter. A value of Integer.MAX_VALUE implies an unlimited number of updates.

public long getMaxWaitTime ()

This method is deprecated.
Use getMaxUpdateDelayMillis() instead. May be removed in a future release.

public float getMinUpdateDistanceMeters ()

The minimum distance required between consecutive location updates. If a derived location update is not at least the specified distance away from the previous location update delivered to the client, it will not be delivered. This may also allow additional power savings under some circumstances.

public long getMinUpdateIntervalMillis ()

The fastest allowed interval of location updates. Location updates may arrive faster than the desired interval (getIntervalMillis()), but will never arrive faster than specified here. FLP APIs make some allowance for jitter with the minimum update interval, so clients need not worry about location updates that arrive a couple milliseconds too early being rejected.

public int getNumUpdates ()

This method is deprecated.
Use getMaxUpdates() instead. May be removed in a future release.

public int getPriority ()

The Priority of the location request.

public float getSmallestDisplacement ()

This method is deprecated.
Use getMinUpdateDistanceMeters() instead.

public int hashCode ()

public boolean isBatched ()

True if this request allows batching (i.e. getMaxUpdateDelayMillis() is at least 2x getIntervalMillis()). Note that simply because a request allows batching does not guarantee it will receive batched results, as this often depends on hardware support and other factors.

Location requests that are not batched are guaranteed to receive locations that are monotonically increasing in time (they will never receive a location that appears to travel backwards in time compared to the prior location). Location requests that allow for batching may receive such out-of-order locations, and must be prepared to handle such locations correctly for their own needs. Out-of-order locations may not be evaluated against other location request constraints, such as the minimum update interval or minimum update distance, due to their out-of-order nature.

public boolean isFastestIntervalExplicitlySet ()

This method is deprecated.
Do not use. May be removed in a future release.

public boolean isPassive ()

True if the priority is Priority.PRIORITY_PASSIVE.

public boolean isWaitForAccurateLocation ()

If this request is Priority.PRIORITY_HIGH_ACCURACY, this will delay delivery of initial low accuracy locations for a small amount of time in case a high accuracy location can be delivered instead.

public LocationRequest setExpirationDuration (long durationMillis)

This method is deprecated.
Use LocationRequest.Builder.setDurationMillis(long) instead. May be removed in a future release.

public LocationRequest setExpirationTime (long elapsedRealtime)

This method is deprecated.
Use LocationRequest.Builder.setDurationMillis(long) instead. Using this method will express the expiration time in terms of duration, which may give unexpected results. May be removed in a future release.

public LocationRequest setFastestInterval (long fastestIntervalMillis)

This method is deprecated.
Use LocationRequest.Builder.setMinUpdateIntervalMillis(long) instead. May be removed in a future release.

public LocationRequest setInterval (long intervalMillis)

This method is deprecated.
Use LocationRequest.Builder.setIntervalMillis(long) instead. May be removed in a future release.

public LocationRequest setMaxWaitTime (long maxWaitTimeMillis)

This method is deprecated.
Use LocationRequest.Builder.setMaxUpdateDelayMillis(long) instead. May be removed in a future release.

public LocationRequest setNumUpdates (int maxUpdates)

This method is deprecated.
Use LocationRequest.Builder.setMaxUpdates(int) instead. May be removed in a future release.

public LocationRequest setPriority (int priority)

This method is deprecated.
Use LocationRequest.Builder.setPriority(int) instead. May be removed in a future release.

public LocationRequest setSmallestDisplacement (float smallestDisplacementMeters)

This method is deprecated.
Use LocationRequest.Builder.setMinUpdateDistanceMeters(float) instead. May be removed in a future release.

public LocationRequest setWaitForAccurateLocation (boolean waitForAccurateLocation)

This method is deprecated.
Use LocationRequest.Builder.setWaitForAccurateLocation(boolean) instead. May be removed in a future release.

public String toString ()

public void writeToParcel (Parcel parcel, int flags)