LocationRequest.Builder

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 the same as 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

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 the same as 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).

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

The default value is 0.

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 the same as 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.

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.