Click here to see your recently viewed pages and most viewed pages.
Hide
Google Maps Android API

Getting Started

Before you can begin working with the API, you will need to download the API and ensure that you have a Google Maps Android API v2 key. Both the API and the key are freely available.

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:

  1. Install the Android SDK.
  2. Download and configure the Google Play services SDK, which includes the Google Maps Android API. If you use the Google Maps Mobile SDK for Work you must download and configure the Google Maps Mobile SDK for Work static library.
  3. Obtain an API key. To do this, you will need to register a project in the Google Developers Console, and get a signing certificate for your app.
  4. Add the required settings in your application's manifest.
  5. Add a map to your application.
  6. Publish your application.

You may wish to begin by looking at some sample code, which is included with the Google Play services SDK.

Install the Android SDK

As a prerequisite, you need to install the Android SDK. See Get 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.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Get an Android certificate and the Google Maps API key

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

Note: Refer to the Android guide to Signing Your Applications for more information regarding digital certificates.

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.

  1. Retrieve information about your application's certificate.
  2. Register a project in the Google Developers Console and add the Maps API as a service for the project.
  3. Request one or more keys.
  4. Add your key to your application and begin development.

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.

You can display a certificate's SHA-1 fingerprint using the keytool program with the -v parameter. For more information about Keytool, see the documentation at http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html.

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

Create an API project in the Google Developers Console

Follow these steps to create or modify a project for your application in the Google Developers Console and enable the Google Maps Android API.

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one.
  3. In the sidebar on the left, expand APIs & auth. Next, click APIs. Select the Enabled APIs link in the API section to see a list of all your enabled APIs. Make sure that the API is on the list of enabled APIs. If you have not enabled it, select the API from the list of APIs, then select the Enable API button for the API. The only API you need is the Google Maps Android API, although you can choose to enable other APIs for the same project too.
  4. In the sidebar on the left, select Credentials.

Get an Android API key

After following the above steps to activate the API, you end up on the Credentials page in the Google Developers Console, where you can access your project's API keys and other credentials.

  1. If your project doesn't already have a Key for Android applications, create an API key by selecting Create New Key and then selecting Android key.
  2. In the resulting dialog, enter your app's SHA-1 fingerprint, then a semicolon (;) then your app's package name. For example:
    BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;com.example.android.mapexample
  3. The Google Developers Console displays a section titled Key for Android applications 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 Google Maps Android API v2 reads the key value and passes it to the Google Maps server, which then confirms that you have access to Google Maps data.

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

    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="API_KEY"/>
    

    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.

  2. 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 Google Maps Android 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 Developers 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:

The following permissions are recommended, but can be ignored if your application does not access the user's current location, either programmatically, or by enabling the My Location layer.

  • android.permission.ACCESS_COARSE_LOCATION Allows the API to use WiFi or mobile cell data (or both) to determine the device's location.
  • android.permission.ACCESS_FINE_LOCATION Allows the API to use the Global Positioning System (GPS) to determine the device's location to within a very small area.

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

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

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.

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

    <?xml version="1.0" encoding="utf-8"?>
    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
              android:id="@+id/map"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:name="com.google.android.gms.maps.MapFragment"/>
    
  2. Add the following code in MainActivity.java.

    package com.example.mapdemo;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    public class MainActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    }
    
  3. Build and run your application. You should see a map. If you don't see a map, confirm that you've completed all the steps described on this page.