Logo Icon Logo
A Crowd-sourced Cookbook on Writing Great Android® Apps
GitHub logo Twitter logo OReilly Book Cover Art

Getting Ready for Google Maps API V2 Development

Published? true
FormatLanguage: WikiFormat

Problem:

You want to get set up to use the current (V2) Google Maps API.

Solution:

Download Google Play Services, get an API key, import a project or two, and start coding!

Discussion:

The V2 API is easier to use than its predecessor, albeit a bit more setup is needed to get started with it. NOTE: This recipe describes only the V2 API. The V1 API described in recipes 1291 through 462 is deprecated; you can still code to it but, unless you have an API key, you will not be able to run your application, as new API keys are not being issued after March 2013. Those recipes will be removed in a future revision of this book; for this revision we have chosen to cover both.

This points out one drawback of using a proprietary Maps API: you are dependent upon Google for API key access. The OpenStreetMap API covered starting in 2521 does not have this problem; it is entirely open source and open data.

Note that the V2 API can only be used on devices that have Google Play installed, e.g., official Google-branded devices, and which have OpenGL ES 2.0 or later (almost all devices do). Note further that this API carries a *mandatory* "Attribution" requirement, which we'll cover in the 4297.

Contents


Download Google Play Services

The Google Play Services needs to be downloaded using the Android Download Manager, where it is listed under Extras.

Get an API Key

You need an API key to extend Google's use-our-maps permissions to your application. The API key isn't really top secret, as it is baked into the AndroidManifest.xml and shipped with every copy of your app. The data used to generate it, however (the SHA1 from your key signing file) should be treated as highly confidential.

To get started, you have to login to the Google API Console at https://code.google.com/apis/console/. You should create a new Project - don't worry, this doesn't create a new Eclipse project, it is just a way for Google to keep track of your keys.

In the main console, click Services. Then you will see a list of services. Find the one for Google Android Maps v2 near the middle of the list, and click the on/off button:

This will display a list of terms. Be sure you can agree to them, as it is a legal contract.

Then you get to create an API key. They API key needs one or more tuples consisting of a certificate signature and a package name. Note that you will typically actually have two Signing Certificates. The one for development and debug is called debug.keystore, and lives in ~/.android (or in "C:\Users\your_user_name\.android" on current Windows systems). After you cd to the correct .android directory path, you can extract its SHA1 using the following:

keytool -list -v -keystore debug.keystore -alias androiddebugkey \

-storepass android -keypass android

For your production signing key, neither the filename, the alias, or the keystore password are standard, so it takes a bit more work.

keytool -list keystore YOUR_KEYSTORE

keytool -v -list -keystore YOUR_KEYSTORE -alias THE_LISTED_ALIAS

For both invocations of keytool, you will need to enter the keystore password when prompted.

In either case, you will see lines like the following (except there will be hex digits where I have all-zeroes):

Certificate fingerprints:
	 MD5:  4D:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
	 SHA1  0F:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00

To create your API key, copy one of the SHA1 values (just the hex digit string, you should obviously copy and paste it from the terminal window into the browser), along with your application's Java package name, into the small windows. If you have both sha1 keys you can put them here with one per line; if you come back later to add another, you must "Edit Android Apps that can use key" (do *not* create a second key, as this will revoke your previous key!).

When you submit this, your key will be displayed; it is the 40-c-character string after "API Key" (greyed out here since I generated a real key to get this image):

You are ready to install this in your project's Manifest.

Import and Create Project(s)

First, you need to import an Android Library Project. There is no shortcut for this, as this google-play-services_lib project contains not only the Jar file but also ancilliary files like the Internationalized (See xxx) strings.xml file used by the Jar file.

  • Select File -> Import -> Android -> Existing Android Code Into Workspace.
  • Click Next.
  • Select Browse..., navigate to ANDROID-SDK-FOLDER/extras/google/google_play_services/libproject, click on google-play-services_lib, and click Finish.
  • This will create a new library project called google-play-services_lib in your workspace.

The next step depends on whether you are starting from scratch or wanting to add maps to an existing project. If you are starting from scratch, you may want to import the sample maps app project and hack on it until it looks like what you want.

  • Select File -> Import -> Android -> Existing Android Code Into Workspace.
  • Click Next.
  • Select Browse..., enter ANDROID-SDK-FOLDER/extras/google/google_play_services/samples/maps.
  • Click Finish. The project will be created, but will show errors on the res folder.
  • To clear these errrors, add the support jar to this project: Right-click on the project in the Project Explorer, select Build Path, then select Configure Build Path...
  • Select Libraries, then Add External Jars, select the following jar file:

ANDROID-SDK-FOLDER/extras/android/compatibility/v4/android-support-v4.jar

  • Click OK:
  • Add your Google Maps Android V2 API key to the project (see below).
  • Run the project.

To add maps to an existing project, do not add an Eclipse Project Reference in Build Path; instead:

  • Select the project in Package Explorer, then go to the Project Menu and select Properties, or, Right-click on your existing project in the Package Explorer;
  • Select Android;
  • In the Libraries section at the bottom, click Add
  • Select the google-play-services_lib library, and click OK, then Finish.
  • Update the AndroidManifest as per below.

Doing it this way (via Project Properties -> Android) makes sure that Android will include the library jar files in the finished APK; just using Eclipse Project References only adds the jar to your classpath for compilation purposes!

Updating AndroidManifest.xml

You need to make a variety of changes to your AndroidManifest.xml:

  • Add a variety of uses-permission elements, including one for Google Services Framework (gsf);
  • Create a new permission of your own, and a use-permission for it (this is to prevent other applications from directly using your API key);
  • Add your API key as a meta-data inside the application element.

The relevant parts of the AndroidManifest will look something like this:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.darwinsys.mapdemos"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="8"
        android:targetSdkVersion="17" />
    <uses-feature
        android:glEsVersion="0x00020000"
        android:required="true" />
    <permission
          android:name="com.darwinsys.mapdemos.permission.MAPS_RECEIVE"
          android:protectionLevel="signature"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="com.darwinsys.mapdemos.permission.MAPS_RECEIVE"/>
    <uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <meta-data
            android:name="com.google.android.maps.v2.API_KEY"
            android:value="AIzaSyCdJBhaTPQoTYDu4nyNeSpuPN_b4UL-h64" />
        <activity
            android:name="com.darwinsys.mapdemos.MainActivity"
            android:label="@string/app_name" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

The main layout of a trivial Maps app will look like this (activity_main.xml), using a MapFragment:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:tools="http://schemas.android.com/tools"
  android:id="@+id/map"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  class="com.google.android.gms.maps.MapFragment"  
  tools:context=".MainActivity" 
  />

This can be used in the usual way as the main View in onCreate() of an application's main activity:

setContentView(R.layout.activity_main);

If all is well, you should be able to run the application and see a map similar to the following. We will add functionality to it in the following Recipe.

To make the Map more interesting and interactive, continue to 4297.

See Also:

The official Maps documentation is at https://developers.google.com/maps/.

Download:

The source code for this project is in the Android Cookbook repository, http://github.com/IanDarwin/Android-Cookbook-Examples/,in the subdirectory MapDemosV2.