Home | History | Annotate | Download | only in location
      1 page.title=Location and Maps
      2 @jd:body
      3 
      4 <div id="qv-wrapper">
      5 <div id="qv">
      6 
      7   <h2>Location and Maps quickview</h2>
      8   <ul>
      9     <li>Android provides a location framework that your application can use to determine the device's location and bearing and register for updates.</li>
     10     <li>A Google Maps external library is available that lets you display and manage Maps data.</li>
     11   </ul>
     12   <h2>In this document</h2>
     13   <ol>
     14     <li><a href="#location">Location Services</a></li>
     15     <li><a href="#maps">Google Maps External Library</a></li>
     16   </ol>
     17   <h2>See Also</h2>
     18   <ol>
     19     <li><a href="http://code.google.com/android/add-ons/google-apis/index.html">Google APIs add-on download&raquo;</a></li>
     20   </ol>
     21 </div>
     22 </div>
     23 
     24 <p>Location- and maps-based applications and services are compelling for mobile device users. You can build these capabilities into your applications using the classes of the {@link android.location} package and the Google Maps external library. The sections below provide details. </p>
     25 
     26 <h2 id="location">Location Services</h2>
     27 
     28 <p>Android gives your applications access to the location services supported by
     29 the device through the classes in the <code>android.location</code> package. The
     30 central component of the location framework is the 
     31 {@link android.location.LocationManager} system service, which provides an API to
     32 determine location and bearing if the underlying device (if it supports location
     33 capabilities). </p>
     34 
     35 <p>As with other system services, you do not instantiate a LocationManager directly. 
     36 Rather, you request an LocationManager instance from the system by calling 
     37 {@link android.content.Context#getSystemService(String) getSystemService(Context.LOCATION_SERVICE)}. 
     38 The method returns a handle to a new LocationManager instance.</p>
     39 
     40 <p>Once your application has a handle to a LocationManager instance, your application 
     41 will be able to do three things:</p>
     42 
     43 <ul>
     44     <li>Query for the list of all LocationProviders known to the
     45     LocationManager for its last known location.</li>
     46     <li>Register/unregister for periodic updates of current location from a
     47     LocationProvider (specified either by Criteria or name).</li>
     48     <li>Register/unregister for a given Intent to be fired if the device comes
     49     within a given proximity (specified by radius in meters) of a given
     50     lat/long.</li>
     51 </ul>
     52 
     53 <p>However, during initial development in the emulator, you may not have access to real 
     54 data from a real location provider (Network or GPS). In that case, it may be necessary to
     55 spoof some data for your application using a mock location provider.</p>
     56 
     57 <p class="note"><strong>Note:</strong> If you've used mock LocationProviders in
     58 previous versions of the SDK, you can no longer provide canned LocationProviders
     59 in the /system/etc/location directory. These directories will be wiped during boot-up.
     60 Please follow the new procedures outlined below.</p>
     61 
     62 <h3>Providing Mock Location Data</h3>
     63 
     64 <p>When testing your application on the Android emulator, there are a couple different
     65 ways to send it some mock location data: you can use the DDMS tool or the "geo" command 
     66 option in the emulator console.</p>
     67 
     68 <h4 id="ddms">Using DDMS</h4>
     69 <p>With the DDMS tool, you can simulate location data a few different ways:</p>
     70 <ul>
     71     <li>Manually send individual longitude/latitude coordinates to the device.</li>
     72     <li>Use a GPX file describing a route for playback to the device.</li>
     73     <li>Use a KML file describing individual placemarks for sequenced playback to the device.</li>
     74 </ul>
     75 <p>For more information on using DDMS to spoof location data, see the 
     76 <a href="{@docRoot}guide/developing/tools/ddms.html#emulator-control">Using DDMS guide</a>.
     77 
     78 <h4 id="geo">Using the "geo" command in the emulator console</h4>
     79 <p>Launch your application in the Android emulator and open a terminal/console in
     80 your SDK's <code>/tools</code> directory. Connect to the emulator console. Now you can use:</p>
     81 <ul><li><code>geo fix</code> to send a fixed geo-location.
     82 	<p>This command accepts a longitude and latitude in decimal degrees, and
     83 	an optional altitude in meters. For example:</p>
     84 	<pre>geo fix -121.45356 46.51119 4392</pre>
     85     </li>
     86     <li><code>geo nmea</code> to send an NMEA 0183 sentence.
     87 	<p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data).
     88 	For example:</p>
     89 	<pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre>
     90     </li>
     91 </ul>
     92 
     93 <p>For information about how to connect to the emulator console, see 
     94 <a href="{@docRoot}guide/developing/tools/emulator.html#console">Using the Emulator Console</a>.</p>
     95 
     96 <h2 id="maps">Google Maps External Library</h2>
     97 
     98 <p>To make it easier for you to add powerful mapping capabilities to your
     99 application, Google provides a Maps external library that includes the
    100 com.google.android.maps package. The classes of the com.google.android.maps
    101 package offer built-in downloading, rendering, and caching of Maps tiles, as
    102 well as a variety of display options and controls. </p>
    103 
    104 <p>The key class in the Maps package is
    105 <code>com.google.android.maps.MapView</code>, a subclass of 
    106 {@link android.view.ViewGroup ViewGroup}. A MapView displays a map with data obtained
    107 from the Google Maps service. When the MapView has focus, it will capture
    108 keypresses and touch gestures to pan and zoom the map automatically, including
    109 handling network requests for additional maps tiles. It also provides all of the
    110 UI elements necessary for users to control the map. Your application can also
    111 use MapView class methods to control the MapView programmatically and draw a
    112 number of Overlay types on top of the map. </p>
    113 
    114 <p>In general, the MapView class provides a wrapper around the Google Maps API
    115 that lets your application manipulate Google Maps data through class methods,
    116 and it lets you work with Maps data as you would other types of Views.</p>
    117 
    118 <p>The Maps external library is not part of the standard Android library, so it
    119 may not be present on some compliant Android-powered devices. Similarly, the
    120 Maps external library is not included in the standard Android library provided
    121 in the SDK. So that you can develop using the classes of the
    122 com.google.android.maps package, the Maps external library is made available to
    123 you as part of the Google APIs add-on for the Android SDK. </p>
    124 
    125 <p>To learn more about the Maps external library and how to download and use the
    126 Google APIs add-on, visit</p>
    127 
    128 <p style="margin-left:2em;"><a
    129 href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p>
    130 
    131 <p>For your convenience, the Google APIs add-on is also included in the Android
    132 SDK. <!-- To learn now to use the Maps external library in your application, see
    133 [[Using External Libraries]].--></p>
    134 
    135 <p class="note"><strong>Note:</strong> In order to display Google Maps data in a
    136 MapView, you must register with the Google Maps service and obtain a Maps API
    137 Key. For information about how to get a Maps API Key, see <a
    138 href="http://code.google.com/android/add-ons/google-apis/mapkey.html">Obtaining
    139 a Maps API Key</a>.</p>
    140 
    141