A data object that contains quality of service parameters for requests to the
FusedLocationProviderApi.
LocationRequest objects are used to request a quality of service for location updates from
the FusedLocationProviderApi.
For example, if your application wants high accuracy location it should create a location
request with setPriority(int)
set to
PRIORITY_HIGH_ACCURACY and setInterval(long)
to 5 seconds. This would be appropriate for mapping applications that are showing your
location in real-time.
At the other extreme, if you want negligible power impact, but to still receive location
updates when available, then create a location request with setPriority(int)
set to PRIORITY_NO_POWER.
With this request your application will not trigger (and therefore will not receive any power
blame) any location updates, but will receive locations triggered by other applications. This
would be appropriate for applications that have no firm requirement for location, but can
take advantage when available.
In between these two extremes is a very common use-case, where applications definitely
want to receive updates at a specified interval, and can receive them faster when available,
but still want a low power impact. These applications should consider
PRIORITY_BALANCED_POWER_ACCURACY combined with a faster
setFastestInterval(long) (such as 1 minute) and a slower setInterval(long)
(such as 60 minutes). They will only be assigned power blame for the interval set by
setInterval(long),
but can still receive locations triggered by other applications at a rate up to
setFastestInterval(long). This style of request is appropriate for many location
aware applications, including background usage. Do be careful to also throttle
setFastestInterval(long) if you perform heavy-weight work after receiving an
update - such as using the network.
Activities should strongly consider removing all location request when entering the
background (for example at Activity.onPause()),
or at least swap the request to a larger interval and lower quality.
Applications cannot specify the exact location sources, such as GPS, that are used by the LocationClient. In fact, the system may have multiple location sources (providers) running and may fuse the results from several sources into a single Location object.
Location requests from applications with Manifest.permission.ACCESS_COARSE_LOCATION
and not Manifest.permission.ACCESS_FINE_LOCATION
will be automatically throttled to a slower interval, and the location object will be
obfuscated to only show a coarse level of accuracy.
All location requests are considered hints, and you may receive locations that are more/less accurate, and faster/slower than requested.
Constant Summary
| int | PRIORITY_BALANCED_POWER_ACCURACY | Used with
setPriority(int) to request "block" level accuracy. |
| int | PRIORITY_HIGH_ACCURACY | Used with
setPriority(int) to request the most accurate locations available. |
| int | PRIORITY_LOW_POWER | Used with
setPriority(int) to request "city" level accuracy. |
| int | PRIORITY_NO_POWER | Used with
setPriority(int) to request the best accuracy possible with zero
additional power consumption. |
Inherited Constant Summary
Field Summary
| public static final Creator<LocationRequest> | CREATOR |
Public Method Summary
| static LocationRequest |
create()
Create a location request with default parameters.
|
| boolean | |
| long |
getExpirationTime()
Get the request expiration time, in milliseconds since boot.
|
| 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 quality 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)
Set the request expiration time, in millisecond since boot.
|
| LocationRequest |
setFastestInterval(long millis)
Explicitly set the fastest interval for location updates, in milliseconds.
|
| LocationRequest |
setInterval(long millis)
Set the desired interval for active location updates, in milliseconds.
|
| LocationRequest |
setMaxWaitTime(long millis)
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.
|
| 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 the locations services to wait a few 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
Constants
public static final int PRIORITY_BALANCED_POWER_ACCURACY
Used with
setPriority(int) to request "block" level accuracy.
Block level accuracy is considered to be about 100 meter accuracy. Using a coarse accuracy such as this often consumes less power.
public static final int PRIORITY_HIGH_ACCURACY
Used with
setPriority(int) to request the most accurate locations available.
This will return the finest location available.
public static final int PRIORITY_LOW_POWER
Used with
setPriority(int) to request "city" level accuracy.
City level accuracy is considered to be about 10km accuracy. Using a coarse accuracy such as this often consumes less power.
public static final int PRIORITY_NO_POWER
Used with
setPriority(int) to request the best accuracy possible with zero additional
power consumption.
No locations will be returned unless a different client has requested location updates in which case this request will act as a passive listener to those locations.
Fields
public static final Creator<LocationRequest> CREATOR
Public Methods
public static LocationRequest create ()
Create a location request with default parameters.
Default parameters are for a block accuracy, slowly updated location. It can then be
adjusted as required by the applications before passing to the FusedLocationProviderClient.
Returns
- a new location request
public boolean equals (Object object)
public long getExpirationTime ()
Get the request expiration time, in milliseconds since boot.
This value can be compared to SystemClock.elapsedRealtime()
to determine the time until expiration.
Returns
- expiration time of request, in milliseconds since boot including suspend
public long getFastestInterval ()
Get the fastest interval of this request, in milliseconds.
The system will never provide location updates faster than the minimum of
getFastestInterval() and
getInterval().
Returns
- fastest interval in milliseconds, exact
public long getInterval ()
Get the desired interval of this request, in milliseconds.
Returns
- desired interval in milliseconds, inexact
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 used instead.
Returns
- maximum wait time in milliseconds, inexact
See Also
public int getNumUpdates ()
Get the number of updates requested.
By default this is Integer.MAX_VALUE,
which indicates that locations are updated until the request is explicitly removed.
Returns
- number of updates
public int getPriority ()
Get the quality of the request.
Returns
- an accuracy 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 duration begins immediately (and not when the request is passed to the location client), so call this method again if the request is re-used at a later time.
The location client will automatically stop updates after the request expires.
The duration 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 same object, so that setters can be chained
public LocationRequest setExpirationTime (long millis)
Set the request expiration time, in millisecond since boot.
This expiration time uses the same time base as SystemClock.elapsedRealtime().
The location client will automatically stop updates after the request expires.
The duration includes suspend time. Values before SystemClock.elapsedRealtime()
are allowed, but indicate that the request has already expired.
Parameters
| millis | expiration time of request, in milliseconds since boot including suspend |
|---|
Returns
- the same object, so that setters can be chained
public LocationRequest setFastestInterval (long millis)
Explicitly set the fastest interval for location updates, in milliseconds.
This controls the fastest rate at which your application will receive location
updates, which might be faster than
setInterval(long) in some situations (for example, if other applications are
triggering location updates).
This allows your application to passively acquire locations at a rate faster than it actively acquires locations, saving power.
Unlike
setInterval(long), this parameter is exact. Your application will never
receive updates faster than this value.
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, since location updates may be extremely fast on future implementations.
If
setFastestInterval(long) is set slower than
setInterval(long), then your effective fastest interval is
setInterval(long).
Parameters
| millis | fastest interval for updates in milliseconds, exact |
|---|
Returns
- the same object, so that setters can be chained
Throws
| IllegalArgumentException | if the interval is less than zero |
|---|
public LocationRequest setInterval (long millis)
Set the desired interval for active location updates, in milliseconds.
The location client will actively try to obtain location updates for your application at this interval, so it has a direct influence on the amount of power used by your application. Choose your interval wisely.
This interval is inexact. You may not receive updates at all (if no location sources
are available), or you may receive them slower than requested. You may also receive
them faster than requested (if other applications are requesting location at a faster
interval). The fastest rate that that you will receive updates can be controlled with
setFastestInterval(long). By default this fastest rate is 6x the interval
frequency.
Applications with only the coarse location permission may have their interval silently throttled.
An interval of 0 is allowed, but not recommended, since location updates may be extremely fast on future implementations.
setPriority(int) and
setInterval(long) are the most important parameters on a location
request.
Parameters
| millis | desired interval in millisecond, inexact |
|---|
Returns
- the same object, so that setters can be chained
Throws
| IllegalArgumentException | if the interval is less than zero |
|---|
public LocationRequest setMaxWaitTime (long millis)
Sets the maximum wait time in milliseconds for location updates.
If you pass a value at least 2x larger than the interval specified with
setInterval(long), then location delivery may be delayed and multiple
locations can be delivered at once. Locations are determined at the
setInterval(long) rate, but can be delivered in batch after the interval you
set in this method. This can consume less battery and give more accurate locations,
depending on the device's hardware capabilities. You should set this value to be as
large as possible for your needs if you don't need immediate location delivery.
Parameters
| millis | desired maximum wait time in millisecond, inexact |
|---|
Returns
- the same object, 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.
By default locations are continuously updated until the request is explicitly removed, however you can optionally request a set number of updates. For example, if your application only needs a single fresh location, then call this method with a value of 1 before passing the request to the location client.
When using this option care must be taken to either explicitly remove the request
when no longer needed or to set an expiration with (setExpirationDuration(long)
or
setExpirationTime(long). Otherwise in some cases if a location can't be
computed, this request could stay active indefinitely consuming power.
Parameters
| numUpdates | the number of location updates requested |
|---|
Returns
- the same object, 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.
Use with a priority constant such as
PRIORITY_HIGH_ACCURACY. No other values are accepted.
The priority of the request is a strong hint to the LocationClient for which
location sources to use. For example,
PRIORITY_HIGH_ACCURACY is more likely to use GPS, and
PRIORITY_BALANCED_POWER_ACCURACY is more likely to use WIFI & Cell tower
positioning, but it also depends on many other factors (such as which sources are
available) and is implementation dependent.
setPriority(int) and
setInterval(long) are the most important parameters on a location
request.
Parameters
| priority | an accuracy or power constant |
|---|
Returns
- the same object, so that setters can be chained
Throws
| IllegalArgumentException | if the quality 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 the locations services to wait a few seconds for
accurate locations initially, when accurate locations could not be computed on the
device immediately after
PRIORITY_HIGH_ACCURACY request is made. By default the location services
will wait for accurate locations.
Note that this only applies to clients with
PRIORITY_HIGH_ACCURACY requests.
Also note this 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.