public final class

LocationRequest

extends Object
implements Parcelable
java.lang.Object
   ↳ com.google.android.gms.location.LocationRequest

Class Overview

A data object that contains quality of service parameters for requests to the LocationClient.

LocationRequest objects are used to request a quality of service for location updates from the LocationClient.

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 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 ACCESS_COARSE_LOCATION and not 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.

Summary

Constants
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.
[Expand]
Inherited Constants
From interface android.os.Parcelable
Fields
public static final LocationRequestCreator CREATOR
Public Methods
static LocationRequest create()
Create a location request with default parameters.
int describeContents()
boolean equals(Object object)
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.
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()
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 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.

String toString()
void writeToParcel(Parcel parcel, int flags)
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.os.Parcelable

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.

Constant Value: 102 (0x00000066)

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.

Constant Value: 100 (0x00000064)

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.

Constant Value: 104 (0x00000068)

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.

Constant Value: 105 (0x00000069)

Fields

public static final LocationRequestCreator 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 LocationClient.

Returns
  • a new location request

public int describeContents ()

public boolean equals (Object object)

public long getExpirationTime ()

Get the request expiration time, in milliseconds since boot.

This value can be compared to 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 int getNumUpdates ()

Get the number of updates requested.

By default this is 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 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 elapsedRealtime().

The location client will automatically stop updates after the request expires.

The duration includes suspend time. Values before 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 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.

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

public void writeToParcel (Parcel parcel, int flags)