Previous  | Next  | Home

The Maps API Key

 

The MapView class in the Maps external library lets you integrate Google Maps into your application. Because MapView gives you access to Google Maps data, you must register with the Google Maps service before your implementation of MapView will be able to obtain map data.

 

Obtaining and Using a Maps API Key

Registering and using a Maps API Key is free and has two parts:

  1. First you register the MD5 fingerprint of the certificate that will be used to sign your application. The Maps registration service then provides a Maps API Key that is associated with your application's signer certificate.

  2. Then you add a reference to this Maps API Key in each MapView. 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.

We now outline how to implement these two steps; for more details, see Obtaining a Maps API Key.


To keep things simple we shall register using the debug certificate associated with our development machine to obtain a temporary Maps API key. This is adequate for demonstration and development. However, when you publish an app (e.g., deployment through the Android Market) you must digitally sign it and (if you employ Google Maps) before you publish your application you must register for a new Key based on your release certificate, and update the references in your MapViews to this new key.

 

Getting the MD5 Fingerprint of the Debug Certificate

To generate an MD5 fingerprint of the SDK debug certificate, we must first locate the debug keystore. This will depend on the platform in use. For example, some standard locations are


If in doubt, you can locate the debug keystore by using Eclipse and choosing Window > Preferences > Android > Build.

Once you have located the keystore, the following command issued at a shell prompt will return the MD5 fingerprint of the debug certificate: 


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

For example, on one of my Linux systems (named M33) I obtained


   [guidry@m33 ~]$ keytool -list -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android
   androiddebugkey, Jan 26, 2011, PrivateKeyEntry, 
   Certificate fingerprint (MD5): 3C:8D:BD:C1:7F:40:10:82:C9:6B:B1:E2:68:0C:30:13
   [guidry@m33 ~]$

Copy the MD5 fingerprint, as we shall use it shortly to register with the Map service. Now use a browser to go to the sign-up page. To register for a Maps API Key,

  1. You must have a (free) Google account to use the Maps service. If you don't have one already, use the link on the page to sign up for one.

  2. Agree to the terms of service by clicking the checkbox.

  3. Paste into the appropriate form field the MD5 certificate fingerprint that you generated above for the certificate that you are registering.

  4. Click "Generate API Key".

The server will return a page similar to the following figure containing your key string.



Keep the key string in a safe place because you will need it for any mapping application that you write. In the next section we will describe how to use this key.

 

Using the Maps API Key

You must add the Maps API key obtained above to any MapView objects in your application, so that the Maps server will allow them to download map tiles. For Mapviews declared in XML files, the key is added as the value of a special android:apiKey attribute. For example, the Maps API key returned when the MD5 key for M33 obtained above was registered is 


    07WVUg-srWUZbNUe1L0F3PYs0gcOKG-UqXR-DZQ

Thus a MapView on the machine M33 can be registered to receive map data in an application running under the debug certificate by inserting 


    <com.google.android.maps.MapView
        android:layout_width="fill_parent"
        android:layout_height="fill_parent"
        android:enabled="true"
        android:clickable="true"
        android:apiKey="07WVUg-srWUZbNUe1L0F3PYs0gcOKG-UqXR-DZQ" />

in the XML layout file for the MapView.


This maps API key is valid only under the debug certificate on a specific machine (M33 in this example), for as long as that debug certificate is valid.
  • If I transfer the application to another machine, I will have to obtain a map key for that machine in the same way as described above and change the android:apiKey attribute accordingly.

  • Even on a given machine, the debug certificate expires after a year and you must delete it to force acquisition of a new one (see the General heading under Eclipse Tips). If you acquire a new debug certificate, your mapping applications will not be able to obtain data when deployed using the debug certificate until you obtain a new maps API key.

  • Also, each MapView within an application must have its own android:apiKey specification (but you can use the same API key for all).
The reason that all of this seems more involved than it needs to be is basically that Google Maps are compatible with the Android API, but they are licensed separately from Android.

If you instantiate MapView objects directly from code rather than laying out with XML, the Maps API Key string is passed as a parameter in the constructor. For example, assuming the same API key as above,


    myMapView = new MapView(this, "07WVUg-srWUZbNUe1L0F3PYs0gcOKG-UqXR-DZQ");

would register myMapView to receive mapping data.

 

Modifications of the Manifest File

Finally, for your application to use the Maps API key you must declare in the AndroidManifest.xml file that it requires permission to access the internet and that it uses the Google maps library. The first requires an element 


    <uses-permission android:name="android.permission.INTERNET" />

while the second requires an entry


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

that is a child node of the <application> element. For example, 


    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.lightcone.mapoverlaydemo"
        android:versionCode="1"
        android:versionName="1.0">
            <uses-permission android:name="android.permission.INTERNET" />
        <application android:icon="@drawable/icon" android:label="@string/app_name" android:debuggable="true">
            <activity android:name=".MapOverlayDemo"
                    android:label="@string/app_name">
                <intent-filter>
                    <action android:name="android.intent.action.MAIN" />
                    <category android:name="android.intent.category.LAUNCHER" />
                </intent-filter>
            </activity>
            <activity android:name=".ShowTheMap" android:label="Lat/Long Location"> </activity>
            <uses-library android:name="com.google.android.maps" />
        </application>
        <uses-sdk android:minSdkVersion="3" />

</manifest>

Previous  | Next  | Home