LocationRequest | Android Developers

Quicknav Quicknav
Links

- Google Play Developer Console
- Android Developers Blog
- About Android

Android Sites

- Android.com
- Android Developers
- Android Open Source Project

Language
close

- - About
  - Wear
  - TV
  - Auto
- - Get Started
  - Devices
  - Style
  - Patterns
  - Building Blocks
  - Downloads
  - Videos
- - Training
  - API Guides
  - Reference
  - Tools
  - Google Services
  - Samples
- - Google Play
  - Essentials
  - Get Users
  - Engage & Retain
  - Monetize
  - Tools & Reference
  - Developer Stories

## Results

Loading...
Summary: Constants | Inherited Constants | Fields | Methods | Inherited Methods | [Expand All]
public final class

# LocationRequest

extends Object
implements SafeParcelable

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
int | CONTENTS_FILE_DESCRIPTOR |
int | PARCELABLE_WRITE_RETURN_VALUE |
From interface com.google.android.gms.common.internal.safeparcel.SafeParcelable
String | NULL |

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
Object | clone()
boolean | equals(Object arg0)
void | finalize()
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
From interface android.os.Parcelable
abstract int | describeContents()
abstract void | writeToParcel(Parcel arg0, int arg1)

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

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

#### public void writeToParcel (Parcel parcel, int flags)