docs/html/training/basics/location/locationmanager.jd

page.title=Using the Location Manager
parent.title=Making Your App Location Aware
parent.link=index.html

trainingnavtop=true
next.title=Obtaining the Current Location
next.link=currentlocation.html

@jd:body


<!-- This is the training bar -->
<div id="tb-wrapper">
<div id="tb">

<h2>This lesson teaches you to</h2>
<ol>
  <li><a href="locationmanager.html#TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</a></li>
  <li><a href="locationmanager.html#TaskGetLocationManagerRef">Get a Reference to LocationManager</a></li>
  <li><a href="locationmanager.html#TaskPickLocationProvider">Pick a Location Provider</a></li>
  <li><a href="locationmanager.html#TaskVerifyProvider">Verify the Location Provider is Enabled</a></li>
</ol>

<h2>You should also read</h2>

<ul>
  <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li>
</ul>

<h2>Try it out</h2>

<div class="download-box">
<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download
  the sample app</a>
<p class="filename">LocationAware.zip</p>
</div>

</div>
</div>

<p>Before your application can begin receiving location updates, it needs to perform some simple steps to set up access.  In this lesson, you'll learn what these steps entail.</p>

<h2 id="TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</h2>

<p>The first step of setting up location update access is to declare proper permissions in the manifest.  If permissions are missing, the application will get a {@link java.lang.SecurityException} at runtime.</p>

<p>Depending on the {@link android.location.LocationManager} methods used, either {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} or {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission is needed.  For example, you need to declare the {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} permission if your application uses a network-based location provider only.  The more accurate GPS requires the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission.
Note that declaring the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission implies {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} already.</p>

<p>Also, if a network-based location provider is used in the application, you'll need to declare the internet permission as well.</p>

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

<h2 id="TaskGetLocationManagerRef">Get a Reference to LocationManager</h2>

<p>{@link android.location.LocationManager} is the main class through which your application can access location services on Android.  Similar to other system services, a reference can be obtained from calling the {@link android.content.Context#getSystemService(java.lang.String) getSystemService()} method.  If your application intends to receive location updates in the foreground (within an {@link android.app.Activity}), you should usually perform this step in the {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method.</p>

<pre>
LocationManager locationManager =
        (LocationManager) this.getSystemService(Context.LOCATION_SERVICE);
</pre>

<h2 id="TaskPickLocationProvider">Pick a Location Provider</h2>

<p>While not required, most modern Android-powered devices can receive location updates through multiple underlying technologies, which are abstracted to an application as {@link android.location.LocationProvider} objects.  Location providers may have different performance characteristics in terms of time-to-fix, accuracy, monetary cost, power consumption, and so on.  Generally, a location provider with a greater accuracy, like the GPS, requires a longer fix time than a less accurate one, such as a network-based location provider.</p>

<p>Depending on your application's use case, you have to choose a specific location provider, or multiple providers, based on similar tradeoffs.  For example, a points of interest check-in application would require higher location accuracy than say, a retail store locator where a city level location fix would suffice.  The snippet below asks for a provider backed by the GPS.</p>

<pre>
LocationProvider provider =
        locationManager.getProvider(LocationManager.GPS_PROVIDER);
</pre>

<p>Alternatively, you can provide some input criteria such as accuracy, power requirement, monetary cost, and so on, and let Android decide a closest match location provider.  The snippet below asks for a location provider with fine accuracy and no monetary cost.  Note that the criteria may not resolve to any providers, in which case a null will be returned.  Your application should be prepared to gracefully handle the situation.</p>

<pre>
// Retrieve a list of location providers that have fine accuracy, no monetary cost, etc
Criteria criteria = new Criteria();
criteria.setAccuracy(Criteria.ACCURACY_FINE);
criteria.setCostAllowed(false);
...
String providerName = locManager.getBestProvider(criteria, true);

// If no suitable provider is found, null is returned.
if (providerName != null) {
   ...
}
</pre>

<h2 id="TaskVerifyProvider">Verify the Location Provider is Enabled</h2>

<p>Some location providers such as the GPS can be disabled in Settings.  It is good practice to check whether the desired location provider is currently enabled by calling the {@link android.location.LocationManager#isProviderEnabled(java.lang.String) isProviderEnabled()} method.  If the location provider is disabled, you can offer the user an opportunity to enable it in Settings by firing an {@link android.content.Intent} with the {@link android.provider.Settings#ACTION_LOCATION_SOURCE_SETTINGS} action.</p>

<pre>
&#64;Override
protected void onStart() {
    super.onStart();

    // This verification should be done during onStart() because the system calls
    // this method when the user returns to the activity, which ensures the desired
    // location provider is enabled each time the activity resumes from the stopped state.
    LocationManager locationManager =
            (LocationManager) getSystemService(Context.LOCATION_SERVICE);
    final boolean gpsEnabled = locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER);

    if (!gpsEnabled) {
        // Build an alert dialog here that requests that the user enable
        // the location services, then when the user clicks the "OK" button,
        // call enableLocationSettings()
    }
}

private void enableLocationSettings() {
    Intent settingsIntent = new Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS);
    startActivity(settingsIntent);
}
</pre>