Android Obtaining a Maps API Key

Obtaining a Maps API Key

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.The MapView class in the Maps external library 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.

Registering for a Maps API Key is simple, free, and has two parts:

1. 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.
2. 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.

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.

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

• Overview
• Getting the MD5 Fingerprint of Your Signing Certificate
• Getting the MD5 Fingerprint of the SDK Debug Certificate
• Registering the Certificate Fingerprint with the Google Maps Service
• Adding the Maps API Key to your Application
• Final Steps to Enable MapView Elements

Overview

If you aren't yet familiar with how Android applications are signed, make sure to readSigning Your Applications on the Android Developers site, before registering for your API Key.

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 — an alphanumeric string that uniquely identifies the certificate and developer registered with the service.

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:

• References a certificate/developer registered with the service, and
• References a certificate that matches the certificate with which the application (containing the MapView) was signed.

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

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.

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 must reference the Key that is associated with the certificate used to sign the application.

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. If you are not familiar with how Android applications are signed,

When you are preparing to release your application, however, note that you must 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).

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

• To display Maps data in a MapView, you need to register for a Maps API Key
• Each Maps API Key is uniquely associated with a specific certificate, based on an MD5 fingerprint of the certificate
• Each MapView must reference a Maps API Key, and the Key referenced must be registered to the certificate used to sign the application
• All MapView elements in an application can reference the same Maps API Key
• You can register multiple certificates under your developer identity
• 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

Getting the MD5 Fingerprint of Your Signing Certificate

For more information about using Keytool and Jarsigner to sign your application, see Signing Your Applications on the Android Developers site.

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. Before you visit the registration page, use Keytool to generate the fingerprint of the appropriate certificate.

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.

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

Keytool Option	Description
-list	Print an MD5 fingerprint of a certificate.
-keystore <keystore-name>.keystore	The name of the keystore containing the target key.
-storepass <password>	A password for the keystore. 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.
-alias <alias_name>	The alias for the key for which to generate the MD5 certificate fingerprint.
-keypass <password>	The password for the key. 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.

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

$ keytool -list -alias alias_name -keystore my-release-key.keystore

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:

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

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

Getting the MD5 Fingerprint of the SDK Debug Certificate

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.

To generate an MD5 fingerprint of the debug certificate, first locate the debug keystore. By default, build tools create the debug keystore in the active AVD directory. The location of the AVD directories varies by platform:

• Windows Vista: C:\Users\<user>\.android\debug.keystore
• Windows XP: C:\Documents and Settings\<user>\.android\debug.keystore
• OS X and Linux: ~/.android/debug.keystore

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

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

$ keytool -list -alias androiddebugkey \
-keystore <path_to_debug_keystore>.keystore \
-storepass android -keypass android

Registering the Certificate Fingerprint with the Google Maps Service

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

http://code.google. com/android/maps-api-signup.html

To register for a Maps API Key, follow these steps:

1. If you don't have a Google account, use the link on the page to set one up.
2. Read the Android Maps API Terms of Service carefully. If you agree to the terms, indicate so using the checkbox on the screen.
3. Paste the MD5 certificate fingerprint of the certificate that you are registering into the appropriate form field.
4. Click "Generate API Key"

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

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

Note: If you happen to forget your Maps API Key, you can generate a fingerprint for your certificate and register it again. The registration server will give you the same Maps API Key for the specified certificate fingerprint.

Adding the Maps API Key to your Application

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.

For <MapView> elements declared in XML layout files, add the Maps API Key as the value of a special attribute — android:apiKey. For example:

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

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

mMapView = new MapView(this, "example_Maps_ApiKey_String");

For more information about MapView, see the MapView class Documentation.

Final Steps to Enable MapView Elements

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:

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

  <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" />
   ...
   </application>

• Sign your application with the certificate that corresponds to the Maps API Key referenced in your MapView elements.
•