Everyone is familiar with Google Maps. The Maps are available on almost any platform, and whenever you want to look up something on a map, most of the time you will use the one from Google. The Maps are also available for Android, as a control that you can embed in your app and use for various geographic features.
Although MapView itself is quite easy to understand and it has a nice API, creating an app that includes a MapView can be confusing in terms of setup and all the steps you need to do and understand when you do it for the first time. This article will guide you step by step through the process of making a Google Maps enabled app that looks like this:
Step 1: Generating an API key
It costs a lot to Google to provide the Maps service to third-party developers. Although the service itself is free, there are strict terms of usage, and your usage of MapView is controlled via an API key that identifies your specific app to Google.
Thus, before you can even start including a MapView to your app, you need to get an API key. In most cases, you will need two keys - one for debugging/development and one for the production version of your app. I will show how to generate the debug one and you can read the Google docs further about generating the production key.
In order to generate your debug API key for Maps, you need to know where the debug keystore is located. On Windows Vista, it's the C:\Users\\.android\debug.keystore file, while on XP it's C:\Documents and Settings\\.android\debug.keystore and on Linux it's in the .android directory inside your home dir. Then, you need to find your JDK directory and find the keytool executable in the bin subdirectory of the JDK.
Once you've found both the debug keystore and keytool, go ahead and issue a command in the command line:
keytool -list -alias androiddebugkey -keystore c:\Users\User\.android\debug.keystore -storepass android -keypass android
You're going to get a reply like this:
Certificate fingerprint (MD5): B4:76:E0:10:4C:13:A0:A4:0D:XX:XX:XX:XX:XX:XX:XX
The long hex line (MD5 fingerprint) is what you need. Copy it into the clipboard and go to http://code.google.com/android/maps-api-signup.html.
At this point, you need a Google Account. But you probably have it. Read the terms, mark the checkbox and paste in the MD5 fingerprint into the field, then hit Generate API Key. You will get a result like this:
Copy the key and save it somewhere. This is what we need to start developing our map-enabled application.
Step 2: Creating a Google API based project
Now, let's create a new Android app in Eclipse. It's important to choose one of the Google APIs targets when creating the project rather then plain Android. So, for example, you should choose Google APIs/Platform 1.5/Level 3 rather than just Android 1.5.
We need to set up the manifest to include the maps library and the INTERNET permission to allow the control to contact the Maps service:
<?xml version="1.0" encoding="utf-8"?>
<manifest
xmlns:android="http://schemas.android.com/apk/res/android"
package="com.wiseandroid.samples.maps"
android:versionCode="1"
android:versionName="1.0">
<application
android:icon="@drawable/icon"
android:label="@string/app_name">
<activity
android:name=".TestActivity"
android:label="@string/app_name">
<intent-filter>
<action
android:name="android.intent.action.MAIN" />
<category
android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<!-- Enable the maps -->
<uses-library
android:name="com.google.android.maps" />
</application>
<uses-sdk
android:minSdkVersion="3" />
<!-- Allow internet requests -->
<uses-permission
android:name="android.permission.INTERNET" />
</manifest>
Now we should finally be able to add a MapView to the layout.
Step 3: Adding and using MapView
Now, let's add a MapView instance to the layout:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical"
android:layout_width="fill_parent"
android:layout_height="fill_parent">
<com.google.android.maps.MapView
android:id="@+id/map"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:layout_margin="20dip"
android:clickable="true"
android:apiKey="@string/maps_api_key" />
</LinearLayout>
As you might notice, I extracted the API key to strings.xml in the res folder rather than pasting it right into the layout. That allows me more flexibility, for example if I use multiple MapViews and I need to change the key. Also, android:clickable="true" makes the map pan-able for the user.
At this point, we can also reference the MapView in the activity code. However, please note that the activity must be subclassed from MapActivity rather than from plain Activity, to include MapView.
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
MapView mapView = (MapView) findViewById(R.id.map);
mapView.setBuiltInZoomControls(true);
// fly to San Francisco!
mapView.getController().animateTo(new GeoPoint((int)(37.7734f * 1000000),
(int)(-122.4172f * 1000000)));
mapView.getController().setZoom(10);
}
As you can notice, the GeoPoint class accepts int values that are equal to the floating-point coordinate multiplied by 1E6 (1,000,000). That's probably to avoid dealing with floating-point values.
From this point, you can use all the possible MapView API functions that are described in its docs. Have fun!
Author:
Ivan Memruk
mindtherobot.com