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, applications that are showing the user's location in realtime may consider a PRIORITY_HIGH_ACCURACY request with a short interval. At the other extreme, an application that want a negligible power impact while still receiving opportunistic locations could create PRIORITY_NO_POWER request. With this request the application will not trigger any location updates, but can still receive locations updates triggered by other application's location requests. In between these use cases an application can consider a PRIORITY_BALANCED_POWER_ACCURACY request with a reasonable interval and fastest interval. See the documentation around the various parameters of LocationRequest for more information.

Applications should strongly consider using setFastestInterval(long) to limit the fastest rate at which their location callbacks can be invoked (and thus limit the amount of power used and that they may be blamed for).

Applications cannot specify the exact sensors, such as GNSS, that will be used in order to satisfy location requests. In fact, the Fused Location Provider may fuse the results from many different sensors into a single location.

Location requests from applications 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.

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

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_STABILITY_LOCAL
int	PARCELABLE_STABILITY_VINTF
int	PARCELABLE_WRITE_RETURN_VALUE

Field Summary

public static final Creator<LocationRequest>

CREATOR

Public Method Summary

static LocationRequest	create() Create a location request with default parameters (PRIORITY_BALANCED_POWER_ACCURACY and a slowly updated location).
boolean	equals(Object object)
long	getExpirationTime() Get the request expiration time, in elapsed realtime.
long	getFastestInterval() Get the fastest interval of this request, in milliseconds.
long	getInterval() Get the desired interval of this request, in milliseconds.
long	getMaxWaitTime() Gets the maximum wait time in milliseconds for location updates.
int	getNumUpdates() Get the number of updates requested.
int	getPriority() Get the priority of the request.
float	getSmallestDisplacement() Get the minimum displacement between location updates in meters By default this is 0.
int	hashCode()
boolean	isFastestIntervalExplicitlySet() Returns whether or not the fastest interval was explicitly specified for the location request.
boolean	isWaitForAccurateLocation() Returns whether the location services will wait a few seconds initially for accurate locations, if accurate locations cannot be computed on the device for PRIORITY_HIGH_ACCURACY requests.
LocationRequest	setExpirationDuration(long millis) Set the duration of this request, in milliseconds.
LocationRequest	setExpirationTime(long millis) This method is deprecated. Prefer setExpirationDuration(long)
LocationRequest	setFastestInterval(long fastestIntervalMillis) Set the fastest interval in milliseconds for location updates to an explicit value.
LocationRequest	setInterval(long intervalMillis) Set the desired interval for location updates, in milliseconds.
LocationRequest	setMaxWaitTime(long maxWaitTimeMillis) Sets the maximum wait time in milliseconds for location updates.
LocationRequest	setNumUpdates(int numUpdates) Set the number of location updates.
LocationRequest	setPriority(int priority) Set the priority of the request to one of the priority constants in this class.
LocationRequest	setSmallestDisplacement(float smallestDisplacementMeters) Set the minimum displacement between location updates in meters By default this is 0.
LocationRequest	setWaitForAccurateLocation(boolean waitForAccurateLocation) Sets whether the client wants location services to wait a few more seconds for accurate locations initially, when accurate locations could not be computed on the device immediately after PRIORITY_HIGH_ACCURACY request is made.
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 ()

Create a location request with default parameters (PRIORITY_BALANCED_POWER_ACCURACY and a slowly updated location). Clients may further set parameters before using this location request.

Returns

• a new location request

public boolean equals (Object object)

public long getExpirationTime ()

Get the request expiration time, in elapsed realtime.

Returns

• expiration time of request, in milliseconds of elapsed realtime.

public long getFastestInterval ()

Get the fastest interval of this request, in milliseconds.

Returns

• fastest interval in milliseconds

public long getInterval ()

Get the desired interval of this request, in milliseconds.

Returns

• desired interval in milliseconds

public long getMaxWaitTime ()

Gets the maximum wait time in milliseconds for location updates. If the wait time is smaller than the interval requested with setInterval(long), then the interval will be returned instead.

Returns

• maximum wait time in milliseconds

See Also

• setMaxWaitTime(long)

public int getNumUpdates ()

Get the number of updates requested.

By default this is Integer.MAX_VALUE, which indicates that locations are updated indefinitely until the request is removed.

Returns

• number of updates

public int getPriority ()

Get the priority of the request.

Returns

• a priority constant

public float getSmallestDisplacement ()

Get the minimum displacement between location updates in meters

By default this is 0.

Returns

• minimum displacement between location updates in meters

public int hashCode ()

public boolean isFastestIntervalExplicitlySet ()

Returns whether or not the fastest interval was explicitly specified for the location request.

Returns

• True if the fastest interval was explicitly set for the location request; false otherwise

public boolean isWaitForAccurateLocation ()

Returns whether the location services will wait a few seconds initially for accurate locations, if accurate locations cannot be computed on the device for PRIORITY_HIGH_ACCURACY requests.

public LocationRequest setExpirationDuration (long millis)

Set the duration of this request, in milliseconds. The location request will automatically be removed at some point after the duration expires. The duration starts when a location request is made, and includes suspend time. Values less than 0 are allowed, but indicate that the request has already expired.

Parameters

millis	duration of request in milliseconds

Returns

• the LocationRequest, so that setters can be chained

public LocationRequest setExpirationTime (long millis)

This method is deprecated.
Prefer setExpirationDuration(long)

Set the request expiration time, in elapsed realtime. The location request will automatically be remove at some point after the expiration time. Values before SystemClock.elapsedRealtime() are allowed, but indicate that the request has already expired.

Parameters

millis	expiration time of request, in milliseconds of elapsed realtime

Returns

• the LocationRequest, so that setters can be chained

public LocationRequest setFastestInterval (long fastestIntervalMillis)

Set the fastest interval in milliseconds for location updates to an explicit value.

This controls the absolute fastest rate at which a client can receive location updates. Clients can receive locations faster than their desired interval, and this parameter controls the absolute fastest allowed deliver rate. This allows clients to passively acquire locations at a rate faster than their interval.

If you don't call this method, a fastest interval will be selected for you. It will be a value faster than your active interval (setInterval(long)).

An interval of 0 is allowed, but not recommended as this may cause a client to use more power than desired.

Parameters

fastestIntervalMillis	fastest interval for updates in milliseconds

Returns

• the LocationRequest, so that setters can be chained

Throws

IllegalArgumentException	if the interval is less than zero

public LocationRequest setInterval (long intervalMillis)

Set the desired interval for location updates, in milliseconds.

The Fused Location Provider will attempt to obtain location updates for the client at this interval, so it has a direct influence on the amount of power used by your application. Choose your interval wisely.

You may receive updates faster or slower than the desired interval, or not at all (if location is off for example). The fastest rate that that you will receive updates can be controlled via setFastestInterval(long). By default the fastest rate is 6x the interval.

Applications with only the coarse location permission may have their interval throttled.

Parameters

intervalMillis	desired interval in milliseconds

Returns

• the LocationRequest, so that setters can be chained

Throws

IllegalArgumentException	if the interval is less than zero

public LocationRequest setMaxWaitTime (long maxWaitTimeMillis)

Sets the maximum wait time in milliseconds for location updates.

If you pass a value at least 2x larger than the interval specified via setInterval(long), then location delivery may be delayed by up to the maximum wait time so that batches of locations can be delivered at once. Locations are still calculated at the rate set by setInterval(long), but can be delivered in batches in order to consume less battery. If clients do not require immediate location delivery they should consider setting this value as large as reasonably possible.

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

Parameters

maxWaitTimeMillis	desired maximum wait time in millisecond

Returns

• the LocationRequest, so that setters can be chained

Throws

IllegalArgumentException	if the interval is less than zero

public LocationRequest setNumUpdates (int numUpdates)

Set the number of location updates. After the location request has received this number of locations, it will be automatically removed. If this method is not called, a location request will continue to receive locations indefinitely until removed.

If you only need a single location update, prefer using FusedLocationProviderClient.getCurrentLocation(int, CancellationToken).

Consider also setting an explicit duration on a request, so that if locations cannot be derived for whatever reason, this location request does not continue to use power indefinitely.

Parameters

numUpdates	the number of location updates requested

Returns

• the LocationRequest, so that setters can be chained

Throws

IllegalArgumentException	if numUpdates is 0 or less

public LocationRequest setPriority (int priority)

Set the priority of the request to one of the priority constants in this class.

Parameters

priority	an accuracy or power constant

Returns

• the LocationRequest, so that setters can be chained

Throws

IllegalArgumentException	if the priority constant is not valid

public LocationRequest setSmallestDisplacement (float smallestDisplacementMeters)

Set the minimum displacement between location updates in meters

By default this is 0.

Parameters

smallestDisplacementMeters	the smallest displacement in meters the user must move between location updates.

Returns

• the same object, so that setters can be chained

Throws

IllegalArgumentException	if smallestDisplacementMeters is negative

public LocationRequest setWaitForAccurateLocation (boolean waitForAccurateLocation)

Sets whether the client wants location services to wait a few more seconds for accurate locations initially, when accurate locations could not be computed on the device immediately after PRIORITY_HIGH_ACCURACY request is made.

Note that this only applies to clients with PRIORITY_HIGH_ACCURACY requests, and only applies to the initial locations computed right after the location request is added. The following inaccurate locations may still be delivered to the clients without delay.

public String toString ()

public void writeToParcel (Parcel parcel, int flags)