1page.title=Getting the Last Known Location
2trainingnavtop=true
3@jd:body
4
5<div id="tb-wrapper">
6  <div id="tb">
7
8    <h2>This lesson teaches you how to</h2>
9    <ol>
10      <li><a href="#setup">Set Up Google Play Services</a></li>
11      <li><a href="#permissions">Specify App Permissions</a></li>
12      <li><a href="#play-services">Connect to Google Play Services</a></li>
13      <li><a href="#last-known">Get the Last Known Location</a></li>
14    </ol>
15
16    <h2>You should also read</h2>
17    <ul>
18      <li>
19        <a href="{@docRoot}google/play-services/setup.html">Setting up Google Play
20        Services</a>
21      </li>
22    </ul>
23
24    <h2>Try it out</h2>
25    <ul>
26      <li>
27        <a href="https://github.com/googlesamples/android-play-location/tree/master/BasicLocationSample" class="external-link">BasicLocationSample</a>
28      </li>
29    </ul>
30  </div>
31</div>
32
33<p>Using the Google Play services location APIs, your app can request the last
34  known location of the user's device. In most cases, you are interested in the
35  user's current location, which is usually equivalent to the last known
36  location of the device.</p>
37
38<p>Specifically, use the
39  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html">fused
40  location provider</a> to retrieve the device's last known location. The fused
41  location provider is one of the location APIs in Google Play services. It
42  manages the underlying location technology and provides a simple API so that
43  you can specify requirements at a high level, like high accuracy or low power.
44  It also optimizes the device's use of battery power.</p>
45
46<p>This lesson shows you how to make a single request for the location of a
47  device using the
48  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
49  method in the fused location provider.
50
51<h2 id="setup">Set Up Google Play Services</h2>
52
53<p>To access the fused location provider, your app's development project must
54  include Google Play services. Download and install the Google Play services
55  component via the <a href="{@docRoot}tools/help/sdk-manager.html">SDK
56  Manager</a> and add the library to your project. For details, see the guide to
57  <a href="{@docRoot}google/play-services/setup.html">Setting Up Google Play
58  Services</a>.</p>
59
60<h2 id="permissions">Specify App Permissions</h2>
61
62<p>Apps that use location services must request location permissions. Android
63  offers two location permissions:
64  {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION}
65  and
66  {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION}.
67  The permission you choose determines the accuracy of the location returned by
68  the API. If you specify
69  {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION},
70  the API returns a location with an accuracy approximately equivalent to a city
71  block.</p>
72
73<p>This lesson requires only coarse location. Request this permission with the
74  {@code uses-permission} element in your app manifest, as shown in the
75  following example:
76
77<pre>
78&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
79    package="com.google.android.gms.location.sample.basiclocationsample" &gt;
80
81  &lt;uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/&gt;
82&lt;/manifest&gt;
83</pre>
84
85<h2 id="play-services">Connect to Google Play Services</h2>
86
87<p>To connect to the API, you need to create an instance of the
88  Google Play services API client. For details about using the client, see
89  the guide to
90  <a href="{@docRoot}google/auth/api-client.html#Starting">Accessing Google
91  APIs</a>.
92</p>
93
94<p>In your activity's {@link android.app.Activity#onCreate onCreate()} method,
95  create an instance of Google API Client using
96  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html">{@code GoogleApiClient.Builder}</a>.
97  Use the builder to add the
98  <a href="{@docRoot}reference/com/google/android/gms/location/LocationServices.html">{@code LocationServices}</a>
99  API.</p>
100
101<p>The sample app defines a {@code buildGoogleApiClient()} method, called from
102  the activity's {@link android.app.Activity#onCreate onCreate()} method,
103  which includes the following code.</p>
104
105<pre>
106protected synchronized void buildGoogleApiClient() {
107    mGoogleApiClient = new GoogleApiClient.Builder(this)
108        .addConnectionCallbacks(this)
109        .addOnConnectionFailedListener(this)
110        .addApi(LocationServices.API)
111        .build();
112}
113</pre>
114
115<h2 id="last-known">Get the Last Known Location</h2>
116
117<p>Once you have connected to Google Play services and the location services
118  API, you can get the last known location of a user's device. When your app is
119  connected to these you can use the fused location provider's
120  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
121  method to retrieve the device location. The precision of the location returned
122  by this call is determined by the permission setting you put in your app
123  manifest, as described in the <a href="#permissions">Specify App
124  Permissions</a> section of this document.</p>
125
126<p>To request the last known location, call the
127  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
128  method, passing it your instance of the
129  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a>
130  object. Do this in the
131  <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">{@code onConnected()}</a>
132  callback provided by Google API Client, which is called when the client is
133  ready. The following code sample illustrates the request and a simple
134  handling of the response:</p>
135
136<pre>
137public class MainActivity extends ActionBarActivity implements
138        ConnectionCallbacks, OnConnectionFailedListener {
139    ...
140    &#64;Override
141    public void onConnected(Bundle connectionHint) {
142        mLastLocation = LocationServices.FusedLocationApi.getLastLocation(
143                mGoogleApiClient);
144        if (mLastLocation != null) {
145            mLatitudeText.setText(String.valueOf(mLastLocation.getLatitude()));
146            mLongitudeText.setText(String.valueOf(mLastLocation.getLongitude()));
147        }
148    }
149}
150</pre>
151
152<p>The
153  <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html#getLastLocation(com.google.android.gms.common.api.GoogleApiClient)">{@code getLastLocation()}</a>
154  method returns a
155  <a href="{@docRoot}reference/android/location/Location.html">{@code Location}</a>
156  object from which you can retrieve the latitude and longitude coordinates of a
157  geographic location. The location object returned may be null in rare cases
158  when the location is not available.</p>
159
160<p>The next lesson,
161  <a href="receive-location-updates.html">Receiving Location Updates</a>, shows
162  you how to receive periodic location updates.</p>
163