LocationRequest.Builder

Page Summary

• LocationRequest.Builder is used to construct a LocationRequest object.

• It includes constants for implicit maximum update age and minimum update interval, both set to be the same as the interval.

• The builder can be constructed with only an interval, with priority and interval, or by copying values from an existing LocationRequest.

• The builder provides methods to set various parameters for the location request, such as duration, granularity, intervals, update age/delay, maximum updates, minimum distance, and priority.

• The build() method finalizes the configuration and returns the configured LocationRequest.

public static final class LocationRequest.Builder extends Object

Builder for LocationRequest.

Constant Summary

long	IMPLICIT_MAX_UPDATE_AGE	Represents a maximum update age that is the same as the interval.
long	IMPLICIT_MIN_UPDATE_INTERVAL	Represents a minimum update interval that is half the interval.

Public Constructor Summary

	Builder(long intervalMillis) Constructs a Builder with the given interval, and default values for all other fields.
	Builder(int priority, long intervalMillis) Constructs a Builder with the given priority and interval, and default values for all other fields.
	Builder(LocationRequest request) Constructs a Builder with values copied from the given LocationRequest.

Public Method Summary

LocationRequest	build() Builds a new LocationRequest.
LocationRequest.Builder	setDurationMillis(long durationMillis) Sets the duration of this request.
LocationRequest.Builder	setGranularity(int granularity) Sets the Granularity of locations returned for this request.
LocationRequest.Builder	setIntervalMillis(long intervalMillis) Sets the desired interval of location updates.
LocationRequest.Builder	setMaxUpdateAgeMillis(long maxUpdateAgeMillis) Sets the maximum age of an initial historical location delivered for this request.
LocationRequest.Builder	setMaxUpdateDelayMillis(long maxUpdateDelayMillis) Sets the longest a location update may be delayed.
LocationRequest.Builder	setMaxUpdates(int maxUpdates) Sets the maximum number of updates delivered to this request.
LocationRequest.Builder	setMinUpdateDistanceMeters(float minUpdateDistanceMeters) Sets the minimum distance required between consecutive location updates.
LocationRequest.Builder	setMinUpdateIntervalMillis(long minUpdateIntervalMillis) Sets the fastest allowed interval of location updates.
LocationRequest.Builder	setPriority(int priority) Sets the Priority of the location request.
LocationRequest.Builder	setWaitForAccurateLocation(boolean waitForAccurateLocation) If set to true and 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.

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()

Constants

public static final long IMPLICIT_MAX_UPDATE_AGE

Represents a maximum update age that is the same as the interval.

Constant Value: -1

public static final long IMPLICIT_MIN_UPDATE_INTERVAL

Represents a minimum update interval that is half the interval.

Constant Value: -1

Public Constructors

public Builder (long intervalMillis)

Constructs a Builder with the given interval, and default values for all other fields.

public Builder (int priority, long intervalMillis)

Constructs a Builder with the given priority and interval, and default values for all other fields.

public Builder (LocationRequest request)

Constructs a Builder with values copied from the given LocationRequest.

Public Methods

public LocationRequest build ()

Builds a new LocationRequest.

public LocationRequest.Builder setDurationMillis (long durationMillis)

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

The default value is Long.MAX_VALUE.

public LocationRequest.Builder setGranularity (int granularity)

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

The default value is Granularity.GRANULARITY_PERMISSION_LEVEL.

public LocationRequest.Builder setIntervalMillis (long intervalMillis)

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

The request interval is NOT intended to control how fast an initial location will be delivered to you - it controls the time period between locations. If clients need an immediate single location then please use FusedLocationProviderClient.getCurrentLocation(CurrentLocationRequest, CancellationToken) instead. See setMaxUpdateAgeMillis(long) for additional options that may affect the initial location delivery.

An interval of 0 implies that location should be delivered as fast as the device can support, and some Android devices can deliver location much faster than 1Hz. Prefer never to use an interval of 0 unless your application can support much faster than anticipated location deliveries. An interval of 1 second is likely sufficient for the vast majority of "high location rate" applications.

public LocationRequest.Builder setMaxUpdateAgeMillis (long maxUpdateAgeMillis)

Sets 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 may be set to the special value IMPLICIT_MAX_UPDATE_AGE in which case the maximum update age will always be the same as the interval.

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

The default value is IMPLICIT_MAX_UPDATE_AGE.

public LocationRequest.Builder setMaxUpdateDelayMillis (long maxUpdateDelayMillis)

Sets the longest a location update may be delayed. This parameter controls location batching behavior. If this is set to a value greater than 0 and at least 2x larger than the interval specified by setIntervalMillis(long), 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. When the LocationRequest is built, the maximum update delay will be set to the max of the provided maximum update delay and the interval. This normalizes requests without batching to have the maximum update delay equal to the interval.

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 in a batch represents a point in time ~2s after the previous).

Support for batching may vary by device hardware, 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 are not batched (and not passive) are guaranteed to receive only single 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 (or are passive) may receive batches of locations, and batches may be out-of-order with respect to other received batches (within a single batch locations are still guaranteed to be in order). Clients that make batched requests must be prepared to handle such locations correctly for their own needs, and are strongly advised to check the timestamp of each location to determine how to handle it. 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.

The default value is 0.

See Also

• LocationRequest.isBatched()

public LocationRequest.Builder setMaxUpdates (int maxUpdates)

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

The default value is Integer.MAX_VALUE.

public LocationRequest.Builder setMinUpdateDistanceMeters (float minUpdateDistanceMeters)

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

The default value is 0.

public LocationRequest.Builder setMinUpdateIntervalMillis (long minUpdateIntervalMillis)

Sets the fastest allowed interval of location updates. Location updates may arrive faster than the desired interval (setIntervalMillis(long)), but will never arrive faster than specified here.

This may be set to the special value IMPLICIT_MIN_UPDATE_INTERVAL in which case the minimum update interval will be half the interval. FusedLocationProviderClient 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.

The default value is IMPLICIT_MIN_UPDATE_INTERVAL.

public LocationRequest.Builder setPriority (int priority)

Sets the Priority of the location request. See also LocationRequest.isPassive().

The default value is Priority.PRIORITY_BALANCED_POWER_ACCURACY.

public LocationRequest.Builder setWaitForAccurateLocation (boolean waitForAccurateLocation)

If set to true and 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.

The default value is true.