Previous  | Next  | Home

The Maps API Key

 

The GoogleMap class lets you integrate Google Maps into your application but you must register with the Google Maps service before your implementation will be able to obtain map data.

 

Obtaining and Using a Google Maps API Key

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

  1. First you register the SHA-1 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 the Manifest file of your application.

We now outline how to implement these two steps; for more details, see Get the Google 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 Google Play Store) 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 app to this new key. More detail may be found at Signing Your Applications.

 

Getting the SHA-1 Fingerprint of the Debug Certificate

To generate an SHA-1 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. On my Fedora Linux systems, this window will also display the SHA-1 fingerprint that we obtain below from the command line.

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

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

where you should substitute for <path_to_debug_keystore> the path to your keystore. For example, on one of my Linux systems (named M33) I obtained with this command

   [guidry@m33 ~]$ keytool -list -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android
   androiddebugkey, Dec 13, 2013, PrivateKeyEntry, 
   Certificate fingerprint (SHA1): 73:D5:27:C7:82:34:82:9A:6B:63:C4:D9:99:CA:29:EE:18:A2:29:1B

Copy and save the SHA-1 fingerprint, as we shall use it shortly to register with the Map service.


NOTE: The deprecated Version 1 of Google Maps used the MD5 fingerprint. Version 2 has switched to using the (generally thought more secure) SHA-1 fingerprint. Be certain that the fingerprint that you obtain by the above procedure is the SHA-1 fingerprint as the MD5 fingerprint will not work for current applications of Google Maps.

Now use a browser to create an API project in the Google APIs Console.

  1. If you have already used the GoogleAPIs Console to create a project, skip 1-4 and go directly to the instructions below to request a Maps API key. If you haven't used the Google APIs Console before, you will be prompted to create a project. In that case, click Create Project which causes the Console to create a new project called API Project. On the next page, this name appears in the upper left hand corner. To rename or manage the project, click on its name.

  2. If you have already created the project, you should see a list of your existing projects and available services (click the Services button on the left if services are not displayed).

  3. Scroll down the list of services (there are many) until you find Google Maps Android API v2 and click the button to its right to turn it on (be certain to select the right one; there may be several maps API options displayed with similar names).

  4. You will be presented with a terms of service agreement that you should agree to.

Now we can request a Maps API key.

  1. Navigate to your project in the Google APIs Console.

  2. Click API Access in the left navigation bar.

  3. This window will display a list of any keys that you have previously created. To create a new key, click Create New Android Key (there are multiple buttons for different kinds of keys; be sure to select the right one).

  4. In the window that opens, paste the SHA-1 key from your machine into the input field, followed by a semicolon and the full package name for your app, as illustrated in the following figure.


The server will add an entry to the page that contains the map key and will look like the following,

with the generated 40-character key displayed in the first line.

 

Using the Maps API Key

Now we need to insert a tag in the project Manifest file that specifies this key so that the maps server will know that you have permission to download map data. Copy the key from the webpage above, open the AndroidManifest.xml file for your project, and insert the following tag inside the <application>...</application> tag.

   <!-- GoogleMaps api key-->
   <meta-data
   android:name="com.google.android.maps.v2.API_KEY"
   android:value="api_key" />

where you should substitute for "api_key" the 40-character map key obtained above. This will make the maps API key visible to any MapFragment contained in your application. A general introduction to using Google Maps in Android may be found in the project Map Example. There we discuss additional permissions that must be declared in the manifest file and library accesses that must be enabled to use maps effectively.


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 you transfer the application to another machine, you will have to obtain a map key for that machine in the same way as described above and change the entry in the Manifest file 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.

The reason that all of this may seem to be 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.

Last modified: Feb. 10, 2014

Previous  | Next  | Home