docs/html/training/location/retrieve-current.jd

page.title=Getting the Last Known Location
trainingnavtop=true
@jd:body

<div id="tb-wrapper">
  <div id="tb">

    <h2>This lesson teaches you how to</h2>
    <ol>
      <li><a href="#setup">Set Up Google Play Services</a></li>
      <li><a href="#permissions">Specify App Permissions</a></li>
      <li><a href="#play-services">Connect to Google Play Services</a></li>
      <li><a href="#last-known">Get the Last Known Location</a></li>
    </ol>

    <h2>You should also read</h2>
    <ul>
      <li>
        <a href="{@docRoot}google/play-services/setup.html">Setting up Google Play
        Services</a>
      </li>
    </ul>

    <h2>Try it out</h2>
    <ul>
      <li>
        <a href="https://github.com/googlesamples/android-play-location/tree/master/BasicLocationSample" class="external-link">BasicLocationSample</a>
      </li>
    </ul>
  </div>
</div>

<p>Using the Google Play services location APIs, your app can request the last
  known location of the user's device. In most cases, you are interested in the
  user's current location, which is usually equivalent to the last known
  location of the device.</p>

<p>Specifically, use the
  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html">fused
  location provider</a> to retrieve the device's last known location. The fused
  location provider is one of the location APIs in Google Play services. It
  manages the underlying location technology and provides a simple API so that
  you can specify requirements at a high level, like high accuracy or low power.
  It also optimizes the device's use of battery power.</p>

<p>This lesson shows you how to make a single request for the location of a
  device using the
  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
  method in the fused location provider.

<h2 id="setup">Set Up Google Play Services</h2>

<p>To access the fused location provider, your app's development project must
  include Google Play services. Download and install the Google Play services
  component via the <a href="{@docRoot}tools/help/sdk-manager.html">SDK
  Manager</a> and add the library to your project. For details, see the guide to
  <a href="{@docRoot}google/play-services/setup.html">Setting Up Google Play
  Services</a>.</p>

<h2 id="permissions">Specify App Permissions</h2>

<p>Apps that use location services must request location permissions. Android
  offers two location permissions:
  {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION}
  and
  {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION}.
  The permission you choose determines the accuracy of the location returned by
  the API. If you specify
  {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION},
  the API returns a location with an accuracy approximately equivalent to a city
  block.</p>

<p>This lesson requires only coarse location. Request this permission with the
  {@code uses-permission} element in your app manifest, as the following code
  snippet shows:

<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.google.android.gms.location.sample.basiclocationsample" &gt;

  &lt;uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/&gt;
&lt;/manifest&gt;
</pre>

<h2 id="play-services">Connect to Google Play Services</h2>

<p>To connect to the API, you need to create an instance of the
  Google Play services API client. For details about using the client, see
  the guide to
  <a href="{@docRoot}google/auth/api-client.html#Starting">Accessing Google
  APIs</a>.
</p>

<p>In your activity's {@link android.app.Activity#onCreate onCreate()} method,
  create an instance of Google API Client, using the
  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html">{@code GoogleApiClient.Builder}</a> class to add the
  <a href="{@docRoot}reference/com/google/android/gms/location/LocationServices.html">
  {@code LocationServices}</a>
  API, as the following code snippet shows.</p>

<pre>
// Create an instance of GoogleAPIClient.
if (mGoogleApiClient == null) {
    mGoogleApiClient = new GoogleApiClient.Builder(this)
        .addConnectionCallbacks(this)
        .addOnConnectionFailedListener(this)
        .addApi(LocationServices.API)
        .build();
}
</pre>

<p>To connect, call
<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient#connect()">
  {@code connect()}</a>
  from the activity's
  <a href="{@docRoot}reference/android/app/Activity.html#onStart()">{@code onStart()}</a>
  method. To disconnect, call
  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient#disconnect()">
  {@code disconnect()}</a> from the activity's
  <a href="{@docRoot}reference/android/app/Activity.html#onStop()">
  {@code onStop()}</a> method. The following snippet shows an example of how
  to use both of these methods.
  </p>

<pre>
protected void onStart() {
    mGoogleApiClient.connect();
    super.onStart();
}

protected void onStop() {
    mGoogleApiClient.disconnect();
    super.onStop();
}
</pre>

<h2 id="last-known">Get the Last Known Location</h2>

<p>Once you have connected to Google Play services and the location services
  API, you can get the last known location of a user's device. When your app is
  connected to these you can use the fused location provider's
  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
  method to retrieve the device location. The precision of the location returned
  by this call is determined by the permission setting you put in your app
  manifest, as described in the <a href="#permissions">Specify App
  Permissions</a> section of this document.</p>

<p>To request the last known location, call the
  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
  method, passing it your instance of the
  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a>
  object. Do this in the
  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">{@code onConnected()}</a>
  callback provided by Google API Client, which is called when the client is
  ready. The following code snippet illustrates the request and a simple
  handling of the response:</p>

<pre>
public class MainActivity extends ActionBarActivity implements
        ConnectionCallbacks, OnConnectionFailedListener {
    ...
    &#64;Override
    public void onConnected(Bundle connectionHint) {
        mLastLocation = LocationServices.FusedLocationApi.getLastLocation(
                mGoogleApiClient);
        if (mLastLocation != null) {
            mLatitudeText.setText(String.valueOf(mLastLocation.getLatitude()));
            mLongitudeText.setText(String.valueOf(mLastLocation.getLongitude()));
        }
    }
}
</pre>

<p>The
  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
  method returns a
  <a href="{@docRoot}reference/android/location/Location.html">{@code Location}</a>
  object from which you can retrieve the latitude and longitude coordinates of a
  geographic location. The location object returned may be null in rare cases
  when the location is not available.</p>

<p>The next lesson,
  <a href="change-location-settings.html">Changing Location Settings</a>, shows
  you how to detect the current location settings, and prompt the user to
  change settings as appropriate for your app's requirements.</p>