Friday, December 9, 2011

Google Maps API on Android

At the GR Mobile Dev group this month there was discussion on the topic of using mapping capabilities on the Android and iOS platforms. This document describes the steps necessary to setup an Android application, acquire a API key to access map tiles, and implement a simple mapping application. Below is the basic boilerplate to getting started with the Google Maps API. This doesn't look at any geo-location or overlays, but will get you to the point of being able to start exploring these topics.

Requirements

SDK
The Google Maps API is not part of the core Android SDK, however access to it is available through the Android tool chain. Running the “Android SDK Manager” and verify that the “SDK Platform” and “Google APIs by Google Inc” for the API version you are interested in developing an application are installed (recommend API version 7 [2.1] based on current usage statistics).

AVD (Emulator)
Once the SDK Platform and Google APIs are installed we will need to create an AVD which will support the Google Maps API. The target will need to be set to “Google APIs (Google Inc.) - API Level #” instead of “Android #.# - API Level #” for the Google APIs support. This will create an AVD which includes the normal Android and Google APIs.

Basic Application

Create a basic Android application, except on the step where you select the “Build Target” choose the “Google APIs” for the target API level instead of “Android #.#.” Otherwise the application creation process is the same as the any other project. In the instance where you are working on an already existing project, you can update the project by going to the properties for the project “Android” options and select “Google APIs” for the existing target API level.

Include Map

Manifest
The manifest has two updates required to enable using the Google Maps API. The application will need to know that it should use the Google Maps library. In addition the INTERNET permission is required to load the map tiles.

AndroidManifest.xml
    <manifest ...>
        ...
        <uses-sdk ...>
        <uses-permission android:name="android.permission.INTERNET">
        <application ...>
            <uses-library android:name="com.google.android.maps">
            <activity ...>
        </application>
    </manifest>

Map API Key
Google requires that an application has a map API key to load the map tiles from their servers. This map key is based on the signing key used to sign the application. Under development conditions there is a debug key used to sign the application by the development environment which can be found in ~/.android/debug.keystore, though you will also want to use the release signing key when submitting to the Android Market.

To generate the map API key you will need to use the keytool application which ships with your Java installation. On windows you will find it in the bin directory of your java installation, on Mac OS X or Linux it will probably already be in your path.

Terminal
    % keytool -list -keystore ~/.android/debug.keystore
    ... 
    Certificate fingerprint (MD5): 94:1E:43:49:87:73:BB:E6:A6:88:D7:20:F1:8E:B5:98

Browse to the Map API Key Signup page. Copy the MD5 into the form and submit the form. This will generate the map key for your the debug.keystore. Follow the same steps after you generate a release key for submitting to the Android Market.

Browser - http://code.google.com/android/maps-api-signup.html
    Your key is:
        0UUnupTxbpdGofOV-UQi2jQHV0z6xwGh_kDu3NA

It is good to store the map API key as a value in a strings file to make it easy to change out in case you need to generate a new debug map key for multiple developers working on the project. This file can then be set within the version control system as ignored. Also, a release key can be added and easily be switched between release and production by updating the map_key between @string/map_key_debug and @string/map_key_release.

res/values/map_keys.xml
    <resources>
        <string name="map_key_debug">0UUnupTxbpdGofOV-UQi2jQHV0z6xwGh_kDu3NA</string>
        <string name="map_key_release">0UUnupTxbpdHBqSgZFLLqTmFGezrtAJBEUCUWgw</string>
        <string name="map_key">@string/map_key_debug</string>
    </resources>

Application 

Layout
The layout can now have the map view included. In this example we are using the full screen to display the map view.

res/layout/main.xml
    <linearlayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_height="fill_parent"
        android:layout_width="fill_parent"
        android:orientation="vertical">
        <com.google.android.maps.mapview
            android:id="@+id/map"
            android:apikey="@string/map_key"
            android:layout_height="fill_parent"
            android:layout_width="fill_parent">
        </com.google.android.maps.mapview>
    </linearlayout>

Activity
Maps require that you use a MapActivity. The MapActivity is an abstract class that requires the implementation of the isRouteDisplayed method, though with a simple example this method can be left as a stub returning false. The setupMapView method is setting the map to be clickable and enabling the built in zoom controls.

src/...package.../MainActivity.java
    package ...package...;

    import android.os.Bundle;
    import com.google.android.maps.MapActivity;
    import com.google.android.maps.MapView;

    public class MainActivity
        extends MapActivity {
        @Override
        public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.main);
            setupMapView();
        }

        private void setupMapView() {
            MapView map = (MapView) findViewById(R.id.map);
            map.setBuiltInZoomControls(true);
            map.setClickable(true);
        }

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

Resources

1 comment: