Overview

Creating a new Android application that uses the Google Maps Android API v2
requires several steps. Many of the steps outlined in this section will only
have to be performed once, but some of the information will be a handy
reference for future applications. The overall process of adding a map
to an Android application is as follows:

Install the Android SDK

Install and configure the Google Play services SDK

You will need an Android project for your app, to complete the steps in this
section. If you haven't yet created an Android application, you can follow the
guide to creating a 'hello world' app. See
Creating an Android Project.

The Google Maps Android API v2 is distributed as part of the Google Play
services SDK. You can download the Google Play services SDK via the Android
SDK Manager.

For detailed instructions, see the Google Play services
documentation. Here is a summary of the steps you will need to take:

Install the Google Play services SDK.

Add Google Play services as an Android library project.

Reference the Google Play services in your app's project.

Add the Google Play services version to your app's manifest

Edit your application's AndroidManifest.xml file, and add the following
declaration within the <application> element. This embeds the version of
Google Play services that the app was compiled with.

Get an Android certificate and the Google Maps API key

Note: The Google Maps Android API v2 uses a
new system of managing keys. Existing keys from a Google Maps Android v1
application, commonly known as MapView, will not work with the v2 API.

To access the Google Maps servers with the Maps API, you have to add a Maps
API key to your application. The key is free, you can use it with any of your
applications that call the Maps API, and it supports an unlimited number of
users. You obtain a Maps API key from the Google APIs Console by providing your
application's signing certificate and its package name. Add the key to your
application by adding an element to your application's AndroidManifest.xml
file.

Understanding the process of registering your application and obtaining a key
requires some knowledge of Android's publishing process and requirements. In
summary, all Android applications must be signed with a digital certificate
for which you hold the private key. Because digital certificates are unique,
they provide a simple way of uniquely identifying your app. This makes them
useful for tracking your application in systems such as Google Play Store, and
for tracking your application's use of resources such as the Google Maps
servers.

Maps API keys are linked to specific certificate/package pairs, rather than to
users or applications. You only need one key for each certificate, no matter
how many users you have for an application. Applications that use the same
certificate can use the same API key. However, the recommended practice is to
sign each of your applications with a different certificate and get a
different key for each one.

Obtaining a key for your application requires several steps. These steps are
outlined here, and described in detail in the following sections.

Retrieve information about your application's certificate.

Register a project in the Google APIs Console and add the Maps API as a
service for the project.

Request one or more keys.

Add your key to your application and begin development.

Note: Users of the Google Maps Mobile SDK for Work must
additionally
enable the SDK
for their API project.

Display your app's certificate information

The Maps API key is based on a short form of your application's digital
certificate, known as its SHA-1 fingerprint. The fingerprint is a unique
text string generated from the commonly-used SHA-1 hashing algorithm. Because
the fingerprint is itself unique, Google Maps uses it as a way to identify
your application.

To display the SHA-1 fingerprint for your certificate, first ensure that you
are using the right certificate. You may have two certificates:

Debug certificate: The Android SDK tools generate this certificate
automatically when you do a "debug" build from the command line, or when
you build and run a project from Eclipse without exporting it as a
released application. Only use this certificate with apps that you're
testing; do not attempt to publish an app that's signed with a debug
certificate. The debug certificate is described in more detail in the
section Signing in Debug
Mode
in the Android Developer Documentation.

Release certificate: The Android SDK tools generate this certificate
when you do a "release" build with either ant program or Eclipse. You
can also generate this certificate using the keytool program. Use this
certificate when you are ready to release your app to the world.

Expand the sections below for detailed instructions on how to display
your debug or release certificates.

Displaying the debug certificate fingerprint

Locate your debug keystore file. The file name is debug.keystore, and is
created the first time you build your project. By default, it is stored
in the same directory as your Android Virtual Device (AVD) files:

OS X and Linux: ~/.android/

Windows Vista and Windows 7: C:\Users\your_user_name\.android\

If you are using Eclipse with ADT, and you're not sure where your 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.

The line that begins SHA1 contains the certificate's SHA-1 fingerprint.
The fingerprint is the sequence of 20 two-digit hexadecimal numbers
separated by colons.

Displaying the release certificate fingerprint

Locate your release certificate keystore file. There is no default location
or name for the release keystore. If you don't specify one when you build
your application for release, the build will leave your .apk unsigned,
and you'll have to sign it before you can publish it.
For the release certificate, you also need the certificate's alias and the
passwords for the keystore and the certificate. You can list the aliases
for all the keys in a keystore by entering:

keytool -list -keystore your_keystore_name

Replace your_keystore_name with the fully-qualified path and name of
the keystore, including the .keystore extension. You'll be prompted for
the keystore's password. Once you enter it, keytool displays all the
aliases in the keystore.

Enter the following at a terminal or command prompt:

keytool -list -v -keystore your_keystore_name -alias your_alias_name

Replace your_keystore_name with the fully-qualified path and name of
the keystore, including the .keystore extension. Replace
your_alias_name with the alias that you assigned to the certificate
when you created it.

Caution: To protect your keystore and key, don't
enter the storepass or keypass arguments on the command line unless
you're confident of your computer's security. For example, on a public
computer, someone could look at your terminal window history or list
of running processes, get the password, and then have write access
to your signing certificate. This would allow that person to modify
or replace your application with their own.

Create an API project in the Google APIs Console

If you haven't used the Google APIs Console before, you're prompted to
create a project that you use to track your usage of the Google Maps
Android API. Click Create Project; the Console creates a new project
called API Project. On the next page, this name appears in the upper
left hand corner. To rename or otherwise manage the project, click on
its name.

If you're already using the Google APIs Console, you will immediately
see a list of your existing projects and the available services.
It's still a good idea to use a new project for Google Maps Android
API, so select the project name in the upper left hand corner and then
click Create.

You should see a list of APIs and services in the main window. If you
don't, select Services from the left navigation bar.

In the list of services displayed in the center of the page, scroll down
until you see Google Maps Android API v2. To the right of the entry,
click the switch indicator so that it is on.

This displays the Google Maps Android API Terms of Service.
If you agree to the terms of service, click the checkbox below the terms
of service, then click Accept. This returns you to the list of APIs and
services.

Obtain a Google Maps API key

If your application is registered with the Google Maps Android API v2 service,
then you can request an API key. It's possible to register more than one key
per project.

The Google APIs Console responds by displaying Key for Android apps
(with certificates) followed by a forty-character API key, for example:

AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0

Add the API key to your application

Follow the steps below to include the API key in your application's manifest,
contained in the file AndroidManifest.xml. From there, the Maps API reads the
key value and passes it to the Google Maps server, which then confirms that you
have access to Google Maps data.

In AndroidManifest.xml, add the following element as a child
of the <application>
element, by inserting it just before the closing tag </application>:

Substitute your API key for API_KEY in the value attribute.
This element sets the key com.google.android.geo.API_KEY to the
value of your API key, and makes the API key visible to any
MapFragment in your application.

Save AndroidManifest.xml and re-build your application.

Note: As shown above,
com.google.android.geo.API_KEY is the recommended metadata name
for the API key. A key with this name can be used to authenticate to multiple
Google Maps-based APIs on the Android platform, including the Android Maps
API v2. For backwards compatibility, the API also supports the name
com.google.android.maps.v2.API_KEY. This legacy name allows
authentication to the Android Maps API v2 only. An application can specify
only one of the API key metadata names. If both are specified, the API throws
an exception.

Specify app settings in the application manifest

An Android application that uses the Google Maps Android API should specify
the following settings in its manifest file, AndroidManifest.xml:

A reference to the Google Play services version. If you have followed the
steps on this page up to this point, you have already added the required
declaration to your application manifest.

The Maps API key for the application. The key confirms that you've
registered with the Google Maps service via the Google APIs Console. If you
have followed the steps on this page up to this point, you have already
added the API key to your application manifest.

Permissions that give the application access to Android system features
and to the Google Maps servers. See below for instructions on adding this
setting.

(Recommended) Notification that the application requires OpenGL ES
version 2. External services can detect this notification and act
accordingly. For example, Google Play Store won't display the application on
devices that don't have OpenGL ES version 2. See below for instructions on
adding this setting.

Specify permissions

Specify the permissions your application needs, by adding
<uses-permission>
elements as children of the <manifest> element. The syntax
is:

<uses-permission android:name="permission_name"/>

For example, to request the Internet permission, add:

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

Besides permissions required by other parts of your application, you must
add the following permissions in order to use the Google Maps Android API:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- The following two permissions are not required to use
Google Maps Android API v2, but are recommended. -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Specify requirement for OpenGL ES version 2

The Google Maps Android API uses OpenGL ES version 2 to render the map. If
OpenGL ES version 2 is not installed, your map will not appear. We recommend
that you add the following
<uses-feature>
element as a child of the <manifest> element in
AndroidManifest.xml:

This notifies external services of the requirement. In particular, it has the
effect of preventing Google Play Store from displaying your app on devices
that don't support OpenGL ES version 2.

Add a map

The easiest way to test that your application is configured correctly is to
add a simple map. You will have to make changes in two files: the XML file that
defines the app's layout, and the main activity Java file.

Please note that the code below is only useful for testing your settings in an
application targeting Android API 12 or later. This code should not be used in
a production application. Examples of how to add more robust code appear
throughout this guide and in the sample
code.

Add the following fragment in the app's layout XML file. If you created a
'hello world' app using the Android Developer Tools (ADT) package in Eclipse,
the file is at res/layout/activity-main.xml. Replace the entire contents of
that file with the following code.