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 V1 development

Author: Johan Pelgrim -- Published? false -- FormatLanguage: W

Problem:

You want to get ready to include Google MapView layout elements in your Android app

Solution:

Use the Google Maps API library, a MapView layout element and the MapActivity.

Discussion:

  • Warning* The Google Maps V1 API is deprecated; new code should use the V2 API discussed in Recipes 4285 and 4297.

Let's dig right in by creating an Android project which displays a default map

Contents


Setting up an AVD which makes use of the Google API SDK libraries.

When you create a new Android project you have to indicate which minimum SDK-version your app needs and which SDK-version you target. Since we will be using the Google Maps API we have to make sure we have an AVD with those libraries pre-installed. If you don't work with Google Maps inside your project it is fine to work with an AVD without the Google Maps APIs. In our case we are depenedent on them.

Make sure you have an AVD with a build target of "Google APIs - 1.5 - API level 3".

Create a new Android project which targets "Google APIs - 1.5 - API level 3"

Creating a MapTest project which targets the "Google APIs - 1.5 - API level 3" and uses minSDKversion 3. Let the Android Project wizard create a MapTest activity for you. Click finish.

The MapView element can only live inside a MapActivity, so make sure the MapTest activity extends that class. A MapActivity must implement the isRouteDisplayed() method. This method is required for some accounting from the Maps service to see if you're currently displaying any route information. In this example, we are not. We still have to implement the method, but it's ok to simply return false for now. To be able to zoom in the map we can set the build-in zoom controls to true by calling the setBuiltInZoomControls method on the MapView object.

package nl.codestone.cookbook.maptest;

import android.os.Bundle;

import com.google.android.maps.MapActivity;

public class MapTest extends <tt>MapActivity</tt> {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        MapView mapview = (MapView) findViewById(R.id.mapview);
        mapview.setBuiltInZoomControls(true); 

    }

    @Override
    protected boolean isRouteDisplayed() {
        return false;
    }
}

Adding the MapView element to your layout file

Open the res/layout/main.xml file. Delete the TextView element and replace it with a MapView element

<com.google.android.maps.MapView  
    android:id="@+id/mapview"
    android:layout_width="fill_parent" 
    android:layout_height="fill_parent" 
    android:apiKey="your_api_key_here"
    android:clickable="true"
    />

Some highlights here

  • The MapView is not part of the standard com.android.view package so we have to include the full package name in this element.
  • We have to set the android:clickable attribute to true to be able to drag the map and zoom in and out.
  • Your MapView object has to be configured with a personalized Google Maps API key in a special attribute android:apiKey on the MapView definition. This key can be obtained by registering your MD5 hash from the keystore you sign your apps with (or the debug.keystore during your development cycle).

Registering the Google Maps API key

A full description on how to register a Google Maps API key is given here: http://code.google.com/android/add-ons/google-apis/mapkey.html

This section extracts the minimal steps to get such a key. If you get stuck please refer to the full description by Google.

Android applications have to be signed with a certificate. These certificates are kept in a keystore. For your commercial apps you have to work with a private (self-signed) certificate which is imported in a keystore. When you create and deploy Android applications in your development environment a debug.keystore is used to sign your applications. This debug keystore is located in a .android directory in your user-directory. You need your private androiddebugkey key entry's fingerprint (MD5 hash) to register for a Google Maps API key.

Open a command shell and change to the .android directory which is located in your user directory (e.g. cd ~/.android in unix-like environments)

Issue the following command: keytool -list -alias androiddebugkey -keystore debug.keystore -storepass android

You will be presented with something like this:

androiddebugkey, 29-mrt-2011, PrivateKeyEntry,
Certificate fingerprint (MD5): 2E:54:39:DB:33:E7:D6:3A:9E:18:3D:7F:FB:6D:BC:8D

Copy the bit after Certificate fingerprint (MD5): to your clipboard and go to this page to signup for a Google Maps API key

http://code.google.com/android/maps-api-signup.html

You'll receive a key like this:

18Qcs3h-Sq5l8A7L56bjLwY1gwxgeMYF9Rp_0Cg

Copy and paste this key in the android:apiKey attribute in the MapView element in your res/main.xml layout file. If you are instantiating a MapView directly from code, you should pass the Maps API Key in the MapView constructor.

Tip: You can always regenerate the key as described in the above steps, so there's no need to keep this key somewhere safe. On the other hand, you'd better make a copy of the keystore you use for signing your personal apps!

Necessary changes in the AndroidManifest.xml file

  • You have to register a <uses-permission android:name="android.permission.INTERNET "/> in your AndroidManifest.xml to be able to get Map tiles information from the internet. These map tiles are automatically cached in your apps-data directory, so you don't have to do anything extra for that.
  • The Google Maps classes are not standard, so you have to indicate you use the com.google.android.maps library in your AndroidManifest.xml file.

Example AndroidManifest.xml file

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="nl.codestone.cookbook.maptest"
      android:versionCode="1"
      android:versionName="1.0">
    <uses-sdk android:minSdkVersion="3" />

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

    <application android:icon="@drawable/icon" android:label="@string/app_name">
    
        <activity android:name=".MapTest"
                  android:label="@string/app_name">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

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

    </application>
</manifest>

There's another file called default.properties which contains the build target (level) of your app. This file is automatically generated when you created this project, so no need to change anything. It is good to know that the build target level is defined here if you decide to increase or decrease it at some point. You can either change the level in this file or do it via the project properties dialog in Eclipse.

target=Google Inc.:Google APIs:3

That's it! Start your AVD and run your Android Application. If all's well you should see a map of North and South America which you can drag around and zoom into!

Check List

We end this Recipe with a check list which you can use for quickly setting up projects for the other Google Maps recipes:

  • Use an AVD which makes use of the Google API SDK libraries.
  • Your Activity should extend the MapActivity class.
  • You must implement the isRouteDisplayed() method. The default -- let it return false -- is fine in most cases.
  • Set the build-in zoom controls to true by calling the setBuiltInZoomControls method on the MapView object.
  • Added the full package name to the MapView element in your layout file (i.e. com.google.android.maps.MapView)
  • Add your Google Maps API key to the android:apiKey attribute on the MapView element.
  • If you are instantiating a MapView directly from code, you should pass the Google Maps API Key directly in the MapView constructor.
  • Set the android:clickable attribute on the MapView element to true to be able to drag the map and zoom in and out.
  • Register a <uses-permission android:name="android.permission.INTERNET "/> as a child of the manifest element in your AndroidManifest.xml
  • Register a <uses-library android:name="com.google.android.maps" /> as a child of the application element in your AndroidManifest.xml

See Also:

Google APIs project on Google Code - http://code.google.com/android/add-ons/google-apis Google API key signup page - http://code.google.com/android/maps-api-signup.html

Download:

The source code for this project can be downloaded from https://github.com/downloads/jpelgrim/androidcookbook/MapTest.zip.
No records found.