LocationRequest

AI-generated Key Takeaways

• LocationRequest is used to define parameters for requesting location updates via FusedLocationProviderClient.

• Different scenarios may require varying request parameters, such as priority and interval, to balance accuracy and power consumption.

• Consider using setMinUpdateIntervalMillis() to control the fastest rate of location callbacks and manage power usage.

• Location requests from clients with only coarse location permission may be throttled and obfuscated.

• Many location request parameters serve as hints, meaning the actual location results may differ from the requested accuracy and speed.

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

From interface android.os.Parcelable

int	CONTENTS_FILE_DESCRIPTOR
int	PARCELABLE_WRITE_RETURN_VALUE

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	hashCode()
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	toString()
void	writeToParcel(Parcel parcel, int flags)

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

From interface android.os.Parcelable

abstract int	describeContents()
abstract void	writeToParcel(Parcel arg0, int arg1)

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)