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.
-- Location Services automatically maintains the user's current location, so all your app has to do - is retrieve it as needed. The location's accuracy is based on the location permissions you've - requested and location sensors that are currently active for the device. -
- Location Services sends the current location to your app through a location client, which is
- an instance of the Location Services class
-LocationClient.
- All requests for location information go through this client.
-
- Note: Before you start the lesson, be sure that your development environment - and test device are set up correctly. To learn more about this, read the - Setup section in the Google Play - services guide. -
- -- Apps that use Location Services must request location permissions. Android has 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 controls the accuracy of the current location. If you request only coarse - location permission, Location Services obfuscates the returned location to an accuracy - that's roughly equivalent to a city block. -
-- Requesting {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION} implies - a request for {@link android.Manifest.permission#ACCESS_COARSE_LOCATION ACCESS_COARSE_LOCATION}. -
-
- For example, to add {@link android.Manifest.permission#ACCESS_COARSE_LOCATION
- ACCESS_COARSE_LOCATION}, insert the following as a child element of the
- <manifest>
- element:
-
-<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> -- -
- Location Services is part of the Google Play services APK. Since it's hard to anticipate the
- state of the user's device, you should always check that the APK is installed before you attempt
- to connect to Location Services. To check that the APK is installed, call
-GooglePlayServicesUtil.isGooglePlayServicesAvailable(),
- which returns one of the
- integer result codes listed in the reference documentation for
-ConnectionResult.
- If you encounter an error, call
-GooglePlayServicesUtil.getErrorDialog()
- to retrieve localized dialog that prompts users to take the correct action, then display
- the dialog in a {@link android.support.v4.app.DialogFragment}. The dialog may allow the
- user to correct the problem, in which case Google Play services may send a result back to your
- activity. To handle this result, override the method
- {@link android.support.v4.app.FragmentActivity#onActivityResult onActivityResult()}.
-
- Since you usually need to check for Google Play services in more than one place in your code, - define a method that encapsulates the check, then call the method before each connection - attempt. The following snippet contains all of the code required to check for Google - Play services: -
-
-public class MainActivity extends FragmentActivity {
- ...
- // Global constants
- /*
- * Define a request code to send to Google Play services
- * This code is returned in Activity.onActivityResult
- */
- private final static int
- CONNECTION_FAILURE_RESOLUTION_REQUEST = 9000;
- ...
- // Define a DialogFragment that displays the error dialog
- public static class ErrorDialogFragment extends DialogFragment {
- // Global field to contain the error dialog
- private Dialog mDialog;
- // Default constructor. Sets the dialog field to null
- public ErrorDialogFragment() {
- super();
- mDialog = null;
- }
- // Set the dialog to display
- public void setDialog(Dialog dialog) {
- mDialog = dialog;
- }
- // Return a Dialog to the DialogFragment.
- @Override
- public Dialog onCreateDialog(Bundle savedInstanceState) {
- return mDialog;
- }
- }
- ...
- /*
- * Handle results returned to the FragmentActivity
- * by Google Play services
- */
- @Override
- protected void onActivityResult(
- int requestCode, int resultCode, Intent data) {
- // Decide what to do based on the original request code
- switch (requestCode) {
- ...
- case CONNECTION_FAILURE_RESOLUTION_REQUEST :
- /*
- * If the result code is Activity.RESULT_OK, try
- * to connect again
- */
- switch (resultCode) {
- case Activity.RESULT_OK :
- /*
- * Try the request again
- */
- ...
- break;
- }
- ...
- }
- }
- ...
- private boolean servicesConnected() {
- // Check that Google Play services is available
- int resultCode =
- GooglePlayServicesUtil.
- isGooglePlayServicesAvailable(this);
- // If Google Play services is available
- if (ConnectionResult.SUCCESS == resultCode) {
- // In debug mode, log the status
- Log.d("Location Updates",
- "Google Play services is available.");
- // Continue
- return true;
- // Google Play services was not available for some reason.
- // resultCode holds the error code.
- } else {
- // Get the error dialog from Google Play services
- Dialog errorDialog = GooglePlayServicesUtil.getErrorDialog(
- resultCode,
- this,
- CONNECTION_FAILURE_RESOLUTION_REQUEST);
+Specifically, use the
+ fused
+ location provider 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.
- // If Google Play services can provide an error dialog
- if (errorDialog != null) {
- // Create a new DialogFragment for the error dialog
- ErrorDialogFragment errorFragment =
- new ErrorDialogFragment();
- // Set the dialog in the DialogFragment
- errorFragment.setDialog(errorDialog);
- // Show the error dialog in the DialogFragment
- errorFragment.show(getSupportFragmentManager(),
- "Location Updates");
- }
- }
- }
- ...
-}
-
-- Snippets in the following sections call this method to verify that Google Play services is - available. -
- -
- To get the current location, create a location client, connect it
- to Location Services, and then call its
-getLastLocation()
- method. The return value is the best, most recent location, based on the permissions your
- app requested and the currently-enabled location sensors.
-
-
- Before you create the location client, implement the interfaces that Location Services uses to - communicate with your app: -
-ConnectionCallbacks
- OnConnectionFailedListener
- - The following snippet shows how to specify the interfaces and define the methods: -
-
-public class MainActivity extends FragmentActivity implements
- GooglePlayServicesClient.ConnectionCallbacks,
- GooglePlayServicesClient.OnConnectionFailedListener {
- ...
- /*
- * Called by Location Services when the request to connect the
- * client finishes successfully. At this point, you can
- * request the current location or start periodic updates
- */
- @Override
- public void onConnected(Bundle dataBundle) {
- // Display the connection status
- Toast.makeText(this, "Connected", Toast.LENGTH_SHORT).show();
+This lesson shows you how to make a single request for the location of a
+ device using the
+ {@code getLastLocation()}
+ method in the fused location provider.
- }
+
Set Up Google Play Services
+
+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 SDK
+ Manager and add the library to your project. For details, see the guide to
+ Setting Up Google Play
+ Services.
+
+Specify App Permissions
+
+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.
+
+This lesson requires only coarse location. Request this permission with the
+ {@code uses-permission} element in your app manifest, as shown in the
+ following example:
+
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ package="com.google.android.gms.location.sample.basiclocationsample" >
+
+ <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
+</manifest>
+
+
+Connect to Google Play Services
+
+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
+ Accessing Google
+ APIs.
+
+
+In your activity's {@link android.app.Activity#onCreate onCreate()} method,
+ create an instance of Google API Client using
+ {@code GoogleApiClient.Builder}.
+ Use the builder to add the
+ {@code LocationServices}
+ API.
+
+The sample app defines a {@code buildGoogleApiClient()} method, called from
+ the activity's {@link android.app.Activity#onCreate onCreate()} method,
+ which includes the following code.
+
+
+protected synchronized void buildGoogleApiClient() {
+ mGoogleApiClient = new GoogleApiClient.Builder(this)
+ .addConnectionCallbacks(this)
+ .addOnConnectionFailedListener(this)
+ .addApi(LocationServices.API)
+ .build();
+}
+
+
+Get the Last Known Location
+
+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
+ {@code getLastLocation()}
+ 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 Specify App
+ Permissions section of this document.
+
+To request the last known location, call the
+ {@code getLastLocation()}
+ method, passing it your instance of the
+ {@code GoogleApiClient}
+ object. Do this in the
+ {@code onConnected()}
+ callback provided by Google API Client, which is called when the client is
+ ready. The following code sample illustrates the request and a simple
+ handling of the response:
+
+
+public class MainActivity extends ActionBarActivity implements
+ ConnectionCallbacks, OnConnectionFailedListener {
...
- /*
- * Called by Location Services if the connection to the
- * location client drops because of an error.
- */
@Override
- public void onDisconnected() {
- // Display the connection status
- Toast.makeText(this, "Disconnected. Please re-connect.",
- Toast.LENGTH_SHORT).show();
- }
- ...
- /*
- * Called by Location Services if the attempt to
- * Location Services fails.
- */
- @Override
- public void onConnectionFailed(ConnectionResult connectionResult) {
- /*
- * Google Play services can resolve some errors it detects.
- * If the error has a resolution, try sending an Intent to
- * start a Google Play services activity that can resolve
- * error.
- */
- if (connectionResult.hasResolution()) {
- try {
- // Start an Activity that tries to resolve the error
- connectionResult.startResolutionForResult(
- this,
- CONNECTION_FAILURE_RESOLUTION_REQUEST);
- /*
- * Thrown if Google Play services canceled the original
- * PendingIntent
- */
- } catch (IntentSender.SendIntentException e) {
- // Log the error
- e.printStackTrace();
- }
- } else {
- /*
- * If no resolution is available, display a dialog to the
- * user with the error.
- */
- showErrorDialog(connectionResult.getErrorCode());
+ 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()));
}
}
- ...
}
-
-Connect the Location Client
-
- Now that the callback methods are in place, create the location client and connect it to
- Location Services.
-
-
- You should create the location client in {@link android.support.v4.app.FragmentActivity#onCreate
- onCreate()}, then connect it in
- {@link android.support.v4.app.FragmentActivity#onStart onStart()}, so that Location Services
- maintains the current location while your activity is fully visible. Disconnect the client in
- {@link android.support.v4.app.FragmentActivity#onStop onStop()}, so that when your app is not
- visible, Location Services is not maintaining the current location. Following this pattern of
- connection and disconnection helps save battery power. For example:
-
-
- Note: The current location is only maintained while a location client is
- connected to Location Service. Assuming that no other apps are connected to Location Services,
- if you disconnect the client and then sometime later call
-getLastLocation(),
- the result may be out of date.
-
-
-public class MainActivity extends FragmentActivity implements
- GooglePlayServicesClient.ConnectionCallbacks,
- GooglePlayServicesClient.OnConnectionFailedListener {
- ...
- @Override
- protected void onCreate(Bundle savedInstanceState) {
- ...
- /*
- * Create a new location client, using the enclosing class to
- * handle callbacks.
- */
- mLocationClient = new LocationClient(this, this, this);
- ...
- }
- ...
- /*
- * Called when the Activity becomes visible.
- */
- @Override
- protected void onStart() {
- super.onStart();
- // Connect the client.
- mLocationClient.connect();
- }
- ...
- /*
- * Called when the Activity is no longer visible.
- */
- @Override
- protected void onStop() {
- // Disconnecting the client invalidates it.
- mLocationClient.disconnect();
- super.onStop();
- }
- ...
-}
-
-
-Get the Current Location
-
- To get the current location, call
-getLastLocation().
- For example:
-
-
-public class MainActivity extends FragmentActivity implements
- GooglePlayServicesClient.ConnectionCallbacks,
- GooglePlayServicesClient.OnConnectionFailedListener {
- ...
- // Global variable to hold the current location
- Location mCurrentLocation;
- ...
- mCurrentLocation = mLocationClient.getLastLocation();
- ...
-}
-
-
- The next lesson, Receiving Location Updates, shows
- you how to receive periodic location updates from Location Services.
-
+
+The
+ {@code getLastLocation()}
+ method returns a
+ {@code Location}
+ 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.
+
+The next lesson,
+ Receiving Location Updates, shows
+ you how to receive periodic location updates.
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index f3b2693c4cb73..2489b91c1bddf 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -694,7 +694,7 @@ include the action bar on devices running Android 2.1 or higher."