You should also read

Try it out

If your app can continuously track location, it can deliver more relevant
information to the user. For example, if your app helps the user find their
way while walking or driving, or if your app tracks the location of assets, it
needs to get the location of the device at regular intervals. As well as the
geographical location (latitude and longitude), you may want to give the user
further information such as the bearing (horizontal direction of travel),
altitude, or velocity of the device. This information, and more, is available
in the Location object that your app can retrieve
from the
fused
location provider.

While you can get a device's location with
getLastLocation(),
as illustrated in the lesson on
Getting the Last Known Location,
a more direct approach is to request periodic updates from the fused location
provider. In response, the API updates your app periodically with the best
available location, based on the currently-available location providers such
as WiFi and GPS (Global Positioning System). The accuracy of the location is
determined by the providers, the location permissions you've requested, and
the options you set in the location request.

This lesson shows you how to request regular updates about a device's
location using the
requestLocationUpdates()
method in the fused location provider.

Connect to Location Services

Location services for apps are provided through Google Play services and the
fused location provider. In order to use these services, you connect your app
using the Google API Client and then request location updates. For details on
connecting with the
GoogleApiClient,
follow the instructions in
Getting the Last Known Location, including
requesting the current location.

The last known location of the device provides a handy base from which to
start, ensuring that the app has a known location before starting the
periodic location updates. The lesson on
Getting the Last Known Location shows you
how to get the last known location by calling
getLastLocation().
The snippets in the following sections assume that your app has already
retrieved the last known location and stored it as a
Location object in the global variable
mCurrentLocation.

Apps that use location services must request location permissions. In this
lesson you require fine location detection, so that your app can get as
precise a location as possible from the available location providers. Request
this permission with the
uses-permission element in your app manifest, as shown in the
following example:

Set Up a Location Request

To store parameters for requests to the fused location provider, create a
LocationRequest.
The parameters determine the levels of accuracy requested. For details of all
the options available in the location request, see the
LocationRequest
class reference. This lesson sets the update interval, fastest update
interval, and priority, as described below:

Update interval

setInterval()
- This method sets the rate in milliseconds at which your app prefers to
receive location updates. Note that the location updates may be faster than
this rate if another app is receiving updates at a faster rate, or slower
than this rate, or there may be no updates at all (if the device has no
connectivity, for example).

Fastest update interval

setFastestInterval()
- This method sets the fastest rate in milliseconds at which
your app can handle location updates. You need to set this rate because
other apps also affect the rate at which updates are sent. The Google Play
services location APIs send out updates at the fastest rate that any app
has requested with
setInterval().
If this rate is faster
than your app can handle, you may encounter problems with UI flicker or data
overflow. To prevent this, call
setFastestInterval()
to set an upper limit to the update rate.

Priority

setPriority()
- This method sets the priority of the request, which gives the Google Play
services location services a strong hint about which location sources to use.
The following values are supported:

PRIORITY_BALANCED_POWER_ACCURACY
- Use this setting to request location precision to within a city
block, which is an accuracy of approximately 100 meters. This is
considered a coarse level of accuracy, and is likely to consume less
power. With this setting, the location services are likely to use WiFi
and cell tower positioning. Note, however, that the choice of location
provider depends on many other factors, such as which sources are
available.

PRIORITY_HIGH_ACCURACY
- Use this setting to request the most precise location possible. With
this setting, the location services are more likely to use GPS
(Global Positioning System) to determine the location.

PRIORITY_LOW_POWER
- Use this setting to request city-level precision, which is
an accuracy of approximately 10 kilometers. This is considered a
coarse level of accuracy, and is likely to consume less power.

PRIORITY_NO_POWER
- Use this setting if you need negligible impact on power consumption,
but want to receive location updates when available. With this
setting, your app does not trigger any location updates, but
receives locations triggered by other apps.

Create the location request and set the parameters as shown in this
code sample:

The priority of
PRIORITY_HIGH_ACCURACY,
combined with the
ACCESS_FINE_LOCATION
permission setting that you've defined in the app manifest, and a fast update
interval of 5000 milliseconds (5 seconds), causes the fused location
provider to return location updates that are accurate to within a few feet.
This approach is appropriate for mapping apps that display the location in
real time.

Performance hint: If your app accesses the
network or does other long-running work after receiving a location update,
adjust the fastest interval to a slower value. This adjustment prevents your
app from receiving updates it can't use. Once the long-running work is done,
set the fastest interval back to a fast value.

Request Location Updates

Now that you've set up a location request containing your app's requirements
for the location updates, you can start the regular updates by calling
requestLocationUpdates().
Do this in the
onConnected()
callback provided by Google API Client, which is called when the client is
ready.

Depending on the form of the request, the fused location provider either
invokes the
LocationListener.onLocationChanged()
callback method and passes it a Location object, or
issues a
PendingIntent
that contains the location in its extended data. The accuracy and frequency of
the updates are affected by the location permissions you've requested and the
options you set in the location request object.

Notice that the above code snippet refers to a boolean flag,
mRequestingLocationUpdates, used to track whether the user has
turned location updates on or off. For more about retaining the value of this
flag across instances of the activity, see
Save the State of the Activity.

Define the Location Update Callback

The fused location provider invokes the
LocationListener.onLocationChanged()
callback method. The incoming argument is a Location
object containing the location's latitude and longitude. The following snippet
shows how to implement the
LocationListener
interface and define the method, then get the timestamp of the location update
and display the latitude, longitude and timestamp on your app's user
interface:

Stop Location Updates

Consider whether you want to stop the location updates when the activity is
no longer in focus, such as when the user switches to another app or to a
different activity in the same app. This can be handy to reduce power
consumption, provided the app doesn't need to collect information even when
it's running in the background. This section shows how you can stop the
updates in the activity's
onPause() method.

Use a boolean, mRequestingLocationUpdates, to track
whether location updates are currently turned on. In the activity's
onResume() method, check
whether location updates are currently active, and activate them if not:

Save the State of the Activity

A change to the device's configuration, such as a change in screen
orientation or language, can cause the current activity to be destroyed. Your
app must therefore store any information it needs to recreate the activity.
One way to do this is via an instance state stored in a
Bundle object.

The following code sample shows how to use the activity's
onSaveInstanceState()
callback to save the instance state:

Define an updateValuesFromBundle() method to restore
the saved values from the previous instance of the activity, if they're
available. Call the method from the activity's
onCreate() method, as shown in the
following code sample:

@Override
public void onCreate(Bundle savedInstanceState) {
...
updateValuesFromBundle(savedInstanceState);
}
private void updateValuesFromBundle(Bundle savedInstanceState) {
if (savedInstanceState != null) {
// Update the value of mRequestingLocationUpdates from the Bundle, and
// make sure that the Start Updates and Stop Updates buttons are
// correctly enabled or disabled.
if (savedInstanceState.keySet().contains(REQUESTING_LOCATION_UPDATES_KEY)) {
mRequestingLocationUpdates = savedInstanceState.getBoolean(
REQUESTING_LOCATION_UPDATES_KEY);
setButtonsEnabledState();
}
// Update the value of mCurrentLocation from the Bundle and update the
// UI to show the correct latitude and longitude.
if (savedInstanceState.keySet().contains(LOCATION_KEY)) {
// Since LOCATION_KEY was found in the Bundle, we can be sure that
// mCurrentLocationis not null.
mCurrentLocation = savedInstanceState.getParcelable(LOCATION_KEY);
}
// Update the value of mLastUpdateTime from the Bundle and update the UI.
if (savedInstanceState.keySet().contains(LAST_UPDATED_TIME_STRING_KEY)) {
mLastUpdateTime = savedInstanceState.getString(
LAST_UPDATED_TIME_STRING_KEY);
}
updateUI();
}
}

Note: For a more persistent storage, you can
store the user's preferences in your app's
SharedPreferences. Set the shared preference in
your activity's onPause() method, and
retrieve the preference in onResume().
For more information about saving preferences, read
Saving
Key-Value Sets.