Merge branch 'readonly-p4-master'

page.title=Obtaining a Maps API Key

@jd:body

<div class="sidebox"><p>To register for a Maps API Key, read this document and then go to the <a href="http://code.google.com/android/maps-api-signup.html">Android Maps API Key Signup</a> page.</p>

</div>

<p>com.google.android.maps.MapView is a very useful class that lets you easily integrate Google Maps into your application. It provides built-in map downloading, rendering, and caching of Maps tiles, as well as a variety of display options and controls. It provides a wrapper around the Google Maps API that lets your application request and manipulate Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views. </p>

<p>Because MapView gives you access to Google Maps data, you need to register with the Google Maps service and agree to the applicable Terms of Service before your MapView will be able to obtain data from Google Maps. This will apply whether you are developing your application on the emulator or preparing your application for deployment to mobile devices. </p>

<p>Registering for a Maps API Key is simple, free, and has two parts: </p>

<ol>

<li>Registering the MD5 fingerprint of the certificate that you will use to sign your application. The Maps registration service then provides you a Maps API Key that is associated with your application's signer certificate. </li>

<li>Adding a reference to the Maps API Key in each MapView, whether declared in XML or instantiated directly from code. You can use the same Maps API Key for any MapView in any Android application, provided that the application is signed with the certificate whose fingerprint you registered with the service. </li>

</ol>

<p>During registration, you also need to agree to the Maps API Terms of Service, which describe how your application can use the Maps data. In general, the terms of service are permissive and place few restrictions on how you can use the data. For example, the terms allow you to build "friend finder" type applications. </p>

<p>The sections below describe how to obtain your Maps API Key and how to reference it from your MapView elements. </p>

<ul>

<li><a href="#overview">Overview</a></li>

<li><a href="#getfingerprint">Getting the MD5 Fingerprint of Your Signing Certificate</a></li>

<li><a href="#getdebugfingerprint">Getting the MD5 Fingerprint of the SDK Debug Certificate</a></li>

<li><a href="#registering">Registering the Certificate Fingerprint with the Google Maps Service</a></li>

<li><a href="#addingkey">Adding the Maps API Key to your Application</a></li>

<li><a href="#finalsteps">Final Steps to Enable MapView Elements</a></li>

</ul>

<h2 id="overview">Overview</h2>

<p>MapView objects are views that display Maps tiles downloaded from the Google Maps service. To ensure that applications use Maps data in an appropriate manner, the Google Maps service requires application developers to register with the service, agreeing to the Terms of Service and supplying an MD5 fingerprint of the certificate(s) that they will use to sign applications. For each registered certificate fingerprint, the service then provides the developer with a Maps API Key &mdash; an alphanumeric string that uniquely identifies the certificate and developer registered with the service.  </p>

<p>The Google Maps service also requires that each MapView identify itself to the service using a Maps API Key. Before providing Maps tiles to a MapView, the service checks the Maps API Key supplied by the MapView to ensure that it:</p>

<ul>

<li>References a certificate/developer registered with the service, and </li>

<li>References a certificate that matches the certificate with which the application (containing the MapView) was signed. </li>

</ul>

<p>Unless both conditions are met, the service does not provide Maps tiles to the MapView. </p>

<p>Each MapView object in your application must reference a Maps API Key. Since the Key is associated with a certificate, all Mapview elements in an application should reference the same Key. Going a step further, all MapView elements in all applications that you sign with the same certificate should reference the same Key. </p>

<p>On the other hand, you can register for multiple Maps API Keys, each being associated with a specific certificate. You would want to do this if, for example, you were developing several independent applications that you will sign using different certificates. In this case, note that all MapView elements in a given application can reference the same Maps API Key, but <em>must</em> reference the Key that is associated with the certificate used to sign the application. </p>

<p>Because MapView elements must refer to a Maps API Key, you need to register your certificate and receive a Key before you can make use of MapView elements in your application. To make it easier for you to get started using MapView elements, you are welcome to register the debug certificate generated by the SDK tools and receive a temporary Maps API Key. The details of how to do that are given below. </p>

<p>When you are preparing to release your application, however, note that you <em>must</em> sign your application with a suitable cryptographic key, rather than the SDK debug key. That means that you will also need to register your application's release certificate with the Google Maps service. After you've done so, you will receive a new Maps API Key that is uniquely associated with your release certificate. To enable the MapView elements in your application to work after release, you must remember to change the Maps API Key for all MapViews in your application so that they refer to the Key associated with your release certificate (rather than your debug certificate). </p>

<p>To summarize, the important points to understand about MapViews and the Maps API Key are: </p>

<ul>

<li>To display Maps data in a MapView, you need to register for a Maps API Key</li>

<li>Each Maps API Key is uniquely associated with a specific certificate, based on an MD5 fingerprint of the certificate </li>

<li>Each MapView must reference a Maps API Key, and the Key referenced must be registered to the certificate used to sign the application</li>

<li>All MapView elements in an application can reference the same Maps API Key</li>

<li>You can register multiple certificates under your developer identity</li>

<li>You can get a temporary Maps API Key based on your debug certificate, but before you publish your application, you must register for a new Key based on your release certificate and update references in your MapViews accordingly</li>

</ul>

<h2 id="getfingerprint">Getting the MD5 Fingerprint of Your Signing Certificate</h2>

<div class="sidebox">

For more information about using Keytool and Jarsigner to sign your application, see <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.

</div>

<p>To register for a Maps API Key, you need to provide an MD5 fingerprint of the certificate that you will use to sign your application. </p>

<p>Before you visit the registration page, use Keytool to generate the fingerprint of the appropriate certificate. 

<p>First, determine which key you will use to sign your application at release and make sure of the path to the keystore that contains it.</p>

<p>Next, run Keytool with the <code>-list</code> option, against the target keystore and key alias. The table below lists the options you should use.</p>

<table>

<tr>

<th>Keytool Option</th>

<th>Description</th>

</tr>

<tr>

<td><code>-list</code></td><td>Print an MD5 fingerprint of a certificate.</td>

</tr>

<tr>

<td><code>-keystore&nbsp;&lt;keystore-name&gt;.keystore</code></td><td>The name of the keystore containing the target key.</td>

</tr>

<tr>

<td><code>-storepass &lt;password&gt;</code></td><td><p>A password for the

keystore.</p><p>As a security precaution, do not include this option 

in your command line unless you are working at a secure computer.

If not supplied, Keytool prompts you to enter the password. In this 

way, your password is not stored in your shell history.</p></td>

</tr>

<tr>

<td><code>-alias &lt;alias_name&gt;</code></td><td>The alias for the key for which to generate the MD5 certificate fingerprint.</td>

</tr>

<tr>

<td><code>-keypass &lt;password&gt;</code></td><td><p>The password for the key.</p>

<p>As a security precaution, do not include this option 

in your command line unless you are working at a secure computer.

If not supplied, Keytool prompts you to enter the password. In this 

way, your password is not stored in your shell history.</p></td>

</tr>

</table>

<p>Here's an example of a Keytool command that generates an MD5 certificate fingerprint for the key <code>alias_name</code> in the keystore <code>my-release-key.keystore</code>:</p>

<pre>$ keytool -list -alias alias_name -keystore my-release-key.keystore</pre>

<p>Keytool will prompt you to enter passwords for the keystore and key. As output of the command, Keytool prints the fingerprint to the shell. For example:</p>

<pre>Certificate fingerprint (MD5): 94:1E:43:49:87:73:BB:E6:A6:88:D7:20:F1:8E:B5:98</pre>

<p>Note that, if you happen to forget your Maps API Key, you can repeat the process described above and register the fingerprint again. The server will give you the same key for the specified certificate fingerprint.</p>

<p>Once you have the fingerprint, you can go to the Maps API registration site, described next.</p>

<h2 id="getdebugfingerprint">Getting the MD5 Fingerprint of the SDK Debug Certificate</h2>

<p>While you are developing and debugging your application, you will likely be

sigining your application in debug mode — that is, the SDK build tools

will automatically sign your application using the debug certificate. To let

your MapView elements properly display Maps data during this period, you should

obtain a temporary Maps API Key registered to the debug certificate. To do so,

you first need to get the MD5 fingerprint of the debug certificate. When

you are ready to release your application, you must register your release

certificate with the Google Maps service and obtain a new Maps API Key. You must

then change the MapView elements in your application to reference the new API

key. </p>

<p>To generate an MD5 fingerprint of the debug certificate, first locate the debug keystore. The location at which the SDK tools create the default debug keystore varies by platform: </p>

<ul>

<li>Windows Vista: <code>C:\Users\&lt;user&gt;\AppData\Local\Android\debug.keystore</code></li>

<li>Windows XP: <code>C:\Documents and Settings\&lt;user&gt;\Local Settings\Application&nbsp;Data\Android\debug.keystore</code></li>

<li>OS X and Linux: <code>~/.android/debug.keystore</code></li>

</ul>

<p>If you are using Eclipse/ADT and are unsure where the debug keystore is located, you can select <strong>Windows</strong> &gt; <strong>Prefs</strong> &gt; <strong>Android</strong> &gt; <strong>Build</strong> to check the full path, which you can then paste into a file explorer to locate the directory containing the keystore.</p>

<p>Once you have located the keystore, use this Keytool command to get the MD5 fingerprint of the debug certificate:</p>

<pre>$ keytool -list -alias androiddebugkey \

-keystore <path_to_debug_keystore>.keystore \

-storepass android -keypass android</pre>

<h2 id="registering">Registering the Certificate Fingerprint with the Google Maps Service</h2>

<p>When you are ready to register for a Maps API Key, load this page in a browser: </p>

<p><a href="http://code.google.com/android/maps-api-signup.html">http://code.google.com/android/maps-api-signup.html</a></p>

<p>To register for a Maps API Key, follow these steps:</p>

<ol>

<li>If you don't have a Google account, use the link on the page to set one up. </li>

<li>Read the Android Maps API Terms of Service carefully. If you agree to the terms, indicate so using the checkbox on the screen. </li>

<li>Paste the MD5 certificate fingerprint of the certificate that you are registering into the appropriate form field.</li>

<li>Click "Generate API Key"</li>

</ol>

<p>The server will handle your request, associating the fingerprint with your developer identity and generating a unique Maps API Key, then returning a results page that gives you your Key string. </p>

<p>To use the Maps API Key string, copy and paste it into your code as described in the next section.</p>

<h2 id="addingkey">Adding the Maps API Key to your Application</h2>

<p>Once you've registered with the Google Maps service and have obtained a Maps API Key, you must add it to your application's MapView objects, so that the Maps server will allow them to download Maps tiles. </p>

<p>For <code>&lt;MapView&gt;</code> elements declared in XML layout files, add the Maps API Key as the value of a special attribute &mdash; <code>android:apiKey</code>. For example: </li>

<pre>&lt;com.google.android.maps.MapView

 android:layout_width="fill_parent"

 android:layout_height="fill_parent"

 android:enabled="true"

 android:clickable="true"

 android:apiKey="example_Maps_ApiKey_String"

 /&gt;</pre>

</li>

<p>For MapView objects instantiated directly from code, pass the Maps API Key string as a parameter in the constructor. For example: </p>

<pre>mMapView = new MapView(this, "example_Maps_ApiKey_String");</pre> 

<p>For more information about MapView, see the MapView class Documentation. </p>

<h2 id="finalsteps">Final Steps to Enable MapView Elements</h2>

<p>If you've added the Maps API Key to the MapViews in your application, here are the final steps to enable the MapView elements to run properly:</p>

<ul>

<li>Make sure that you added a <code>&lt;uses-library&gt;</code> element referencing the external <code>com.google.android.maps</code> library. The element must be a child of the <code>&lt;application&gt;</code> element in the application's manifest. For example: 

<p><pre>&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"

 package="com.example.package.name">

 ...

 <application android:name="MyApplication" >

   <uses-library android:name="com.google.android.maps" />

 ...

 &lt;/application&gt;</pre></p></li>

<li>Sign your application with the certificate that corresponds to the Maps API Key referenced in your MapView elements. </li>

</ul>

<div class="special"><p>Note that, when you are ready to publish your application, you must get a Maps API Key that is based on the certificate that you will use to sign the application for release. You must then change the Maps API Key string referenced by all of your MapView elements, so that they reference the new Key. </p></div>

page.title=Location

page.title=Location and Maps

@jd:body

<div id="qv-wrapper">

<div id="qv">

  <h2>Location and Maps quickview</h2>

  <ul>

    <li>Android provides a location framework that your application can use to determine the device's location and bearing and register for updates.</li>

    <li>A Google Maps external library is available that lets you display and manage Maps data.</li>

  </ul>

  <h2>In this document</h2>

  <ol>

    <li><a href="#location">android.location</a></li>

    <li><a href="#maps">com.google.android.maps</a></li>

    <li><a href="#location">Location Services</a></li>

    <li><a href="#maps">Google Maps External Library</a></li>

  </ol>

  <h2>See Also</h2>

  <ol>

    <li><a href="http://code.google.com/android/add-ons/google-apis/index.html">Google APIs add-on download&raquo;</a></li>

  </ol>

</div>

</div>

<p>The Android SDK includes two packages that provide Android's primary support

for building location-based services:

{@link android.location} and {@link-fixme com.google.android.maps}. 

Please read on below for a brief introduction to each package.</p>

<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>

<h2 id="location">Location Services</h2>

<h2 id="location">android.location</h2>

<p>Android gives your applications access to the location services supported by

the device through the classes in the <code>android.location</code> package. The

central component of the location framework is the 

{@link android.location.LocationManager} system service, which provides an API to

determine location and bearing if the underlying device (if it supports location

capabilities). </p>

<p>This package contains several classes related to

location services in the Android platform. Most importantly, it introduces the 

{@link android.location.LocationManager}

service, which provides an API to determine location and bearing if the

underlying device (if it supports the service). The LocationManager 

should <strong>not</strong> be

instantiated directly; rather, a handle to it should be retrieved via

{@link android.content.Context#getSystemService(String)

getSystemService(Context.LOCATION_SERVICE)}.</p>

<p>As with other system services, you do not instantiate a LocationManager directly. 

Rather, you request an LocationManager instance from the system by calling 

{@link android.content.Context#getSystemService(String) getSystemService(Context.LOCATION_SERVICE)}. 

The method returns a handle to a new LocationManager instance.</p>

<p>Once your application has a handle to the LocationManager, your application

<p>Once your application has a handle to a LocationManager instance, your application 

will be able to do three things:</p>

<ul>

    lat/long.</li>

</ul>

<p>However, during initial development, you may not have access to real 

data from a real location provider (Network or GPS). So it may be necessary to

spoof some data for your application, with some mock location data.</p>

<p>However, during initial development in the emulator, you may not have access to real 

data from a real location provider (Network or GPS). In that case, it may be necessary to

spoof some data for your application using a mock location provider.</p>

<p class="note"><strong>Note:</strong> If you've used mock LocationProviders in

previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders

previous versions of the SDK, you can no longer provide canned LocationProviders

in the /system/etc/location directory. These directories will be wiped during boot-up.

Please follow the new procedures below.</p>

Please follow the new procedures outlined below.</p>

<h3>Providing Mock Location Data</h3>

<p>When testing your application on the Android emulator, there are a couple different

ways to send it some spoof location data: with the DDMS tool or the "geo" command.</p>

ways to send it some mock location data: you can use the DDMS tool or the "geo" command 

option in the emulator console.</p>

<h4 id="ddms">Using DDMS</h4>

<p>With the DDMS tool, you can simulate location data a few different ways:</p>

<p>For more information on using DDMS to spoof location data, see the 

<a href="{@docRoot}guide/developing/tools/ddms.html#emulator-control">Using DDMS guide</a>.

<h4 id="geo">Using the "geo" command</h4>

<h4 id="geo">Using the "geo" command in the emulator console</h4>

<p>Launch your application in the Android emulator and open a terminal/console in

your SDK's <code>/tools</code> directory. Now you can use:</p>

your SDK's <code>/tools</code> directory. Connect to the emulator console. Now you can use:</p>

<ul><li><code>geo fix</code> to send a fixed geo-location.

	<p>This command accepts a longitude and latitude in decimal degrees, and

	an optional altitude in meters. For example:</p>

    </li>

</ul>

<h2 id="maps">com.google.android.maps</h2>

<p>This package introduces a number of classes related to

rendering, controlling, and overlaying customized information on your own

Google Mapified Activity. The most important of which is the 

{@link-fixme com.google.android.maps.MapView} class, which automagically draws you a 

basic Google Map when you add a MapView to your layout. Note that, if you 

want to do so, then your Activity that handles the 

MapView must extend {@link-fixme com.google.android.maps.MapActivity}. </p>

<p>Also note that you must obtain a MapView API Key from the Google Maps

service, before your MapView can load maps data. For more information, see 

<a href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a MapView API Key</a>.</p>

<p>Once you've created a MapView, you'll probably want to use 

{@link-fixme com.google.android.maps.MapView#getController()} to 

retrieve a {@link-fixme com.google.android.maps.MapController}, for controlling and 

animating the map, and {@link-fixme com.google.android.maps.ItemizedOverlay} to

draw {@link-fixme com.google.android.maps.Overlay}s and other information on the Map.</p>

<p>This is not a standard package in the Android library. In order to use it, you must add the following node to your Android Manifest file, as a child of the 

<code>&lt;application></code> element:</p>

<pre>&lt;uses-library android:name="com.google.android.maps" /></pre>

<p>For information about how to connect to the emulator console, see 

<a href="{@docRoot}guide/developing/tools/emulator.html#console">Using the Emulator Console</a>.</p>

<h2 id="maps">Google Maps External Library</h2>

<p>To make it easier for you to add powerful mapping capabilities to your

application, Google provides a Maps external library that includes the

com.google.android.maps package. The classes of the com.google.android.maps

package offer built-in downloading, rendering, and caching of Maps tiles, as

well as a variety of display options and controls. </p>

<p>The key class in the Maps package is

<code>com.google.android.maps.MapView</code>, a subclass of 

{@link android.view.ViewGroup ViewGroup}. A MapView displays a map with data obtained

from the Google Maps service. When the MapView has focus, it will capture

keypresses and touch gestures to pan and zoom the map automatically, including

handling network requests for additional maps tiles. It also provides all of the

UI elements necessary for users to control the map. Your application can also

use MapView class methods to control the MapView programmatically and draw a

number of Overlay types on top of the map. </p>

<p>In general, the MapView class provides a wrapper around the Google Maps API

that lets your application manipulate Google Maps data through class methods,

and it lets you work with Maps data as you would other types of Views.</p>

<p>The Maps external library is not part of the standard Android library, so it

may not be present on some compliant Android-powered devices (although it is

likely to be present on most devices). Similarly, the Maps external library is

not included in the standard Android library provided in the SDK. So that you

can develop using the classes of the com.google.android.maps package, the Maps

external library is made available to you as part of the Google APIs add-on for

the Android SDK. </p>

<p>To learn more about the Maps external library and how to download and use the

Google APIs add-on, visit</p>

<p style="margin-left:2em;"><a

href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p>

<p>For your convenience, the Google APIs add-on is also included in the Android

SDK. <!-- To learn now to use the Maps external library in your application, see

[[Using External Libraries]].--></p>

<p class="note"><strong>Note:</strong> In order to display Google Maps data in a

MapView, you must register with the Google Maps service and obtain a Maps API

Key. For information about how to get a Maps API Key, see <a

href="http://code.google.com/android/add-ons/google-apis/mapkey.html">Obtaining

a Maps API Key</a>.</p>

      'name':"Maps API Key",

      'img':"maps-large.png",

      'title':"Maps API Key",

      'desc':"<p>If you're writing an Android application that uses Google Maps (with MapView), you must register your application to obtain a Maps API Key. Without the key, your maps application will not work on Android devices. Obtaining a key requires just a couple of steps.</p><p><a href='{@docRoot}guide/topics/location/geo/mapkey.html'>Learn how to get a Maps API Key</a></p>"

      'desc':"<p>If you're writing an Android application that uses Google Maps (with MapView), you must register your application to obtain a Maps API Key. Without the key, your maps application will not work on Android devices. Obtaining a key requires just a couple of steps.</p><p><a href='{@docRoot}guide/topics/location/index.html'>Learn more...</a></p>"

    },

    'market': {