GoogleMaps Demo

Here is a simple example of Android Maps v2 using MapFragment. We are assuming that the Google Play services SDK is installed. If you don’t have the SDK, please install before this. See details at here.

New Project

  • File > New > Android Application Project
    • Application Name: MapsDemo
    • Package Name: edu.kettering.mapsdemo
    • Minimum Required SDK: API 11: Android 3.0
      • Note: Fragment was introduced in API 11
    • Compile With: Google APIs (Google Inc.) (API 17)
      • If you have not installed Google APIs, Install it using the Android SKD Manager. Google APIs are the superset of Android APIs. This means “Google API level 17” means “Android 4.2.2 (level 17) + Google APIs.”
  • Use default values for all the options.

Adding Library

Add Google Play services library.

  • Project > Properties.
  • Select Android in the left. Find the Library pane. Click “Add…” and select “google-play-services_lib”

Adding MapFragment

  • Open “activity_main.xml” and delete the text view.
  • Drag the “Fragment” in the “Layout” Palette and drop on the main layout.
    • “Choose Fragment Class” will be prompted.
    • Find “MapFragment.”
  • Align the fragment by adjusting the size. The root layout is RelativeLayout. So drag the border lines and drop at the end of the window left, top, right, and bottom.
  • Change the id to “@+id/map”

[code language=”xml”]
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:paddingBottom="@dimen/activity_vertical_margin"
android:paddingLeft="@dimen/activity_horizontal_margin"
android:paddingRight="@dimen/activity_horizontal_margin"
android:paddingTop="@dimen/activity_vertical_margin"
tools:context=".MainActivity" >

<fragment
android:id="@+id/map"
android:name="com.google.android.gms.maps.MapFragment"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentBottom="true"
android:layout_alignParentLeft="true"
android:layout_alignParentTop="true" />

</RelativeLayout>
[/code]

Using GoogleMap class

We can get a GoogleMap object using FragmentManager. A MapFragment can be acquired from findFragmentById. The map can get from getMap().

[code language=”java”]
package edu.kettering.mapsdemo;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.MapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

import android.app.Activity;
import android.os.Bundle;
import android.view.Menu;

public class MainActivity extends Activity {
static final LatLng ketteringLatLng = new LatLng(43.013651,-83.713498);
private GoogleMap map;

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

map = ((MapFragment)getFragmentManager().findFragmentById(R.id.map)).getMap();
map.addMarker(new MarkerOptions().position(ketteringLatLng).title("Kettering"));
map.moveCamera(CameraUpdateFactory.newLatLngZoom(ketteringLatLng, 15));
}

@Override
public boolean onCreateOptionsMenu(Menu menu) {
// Inflate the menu; this adds items to the action bar if it is present.
getMenuInflater().inflate(R.menu.main, menu);
return true;
}

}
[/code]

Getting an API Key

Get an API Key with the package name, “edu.kettering.mapsdemo” and the SHA-1 fingerprint. See this article for more detail.

Editing AndroidManifest.xml

We need to add permission, uses-permission, use-feature, and meta-data. “edu.kettering.mapsdemo”s in red should be replaced with your app’s package name.

[code language=”java”]
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="edu.kettering.mapsdemo"
android:versionCode="1"
android:versionName="1.0" >

<uses-sdk
android:minSdkVersion="11"
android:targetSdkVersion="17" />

<!– Start Maps –>
<permission
android:name="edu.kettering.mapsdemo.permission.MAPS_RECEIVE"
android:protectionLevel="signature"/>
<uses-permission android:name="edu.kettering.mapsdemo.permission.MAPS_RECEIVE" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
<uses-feature
android:glEsVersion="0x00020000"
android:required="true"/>
<!– End of Maps –>

<application
android:allowBackup="true"
android:icon="@drawable/ic_launcher"
android:label="@string/app_name"
android:theme="@style/AppTheme" >

<!– Start Maps –>
<meta-data
android:name="com.google.android.maps.v2.API_KEY"
android:value="YOUR_OWN_KEY"/>
<!– End of Maps –>

<activity
android:name="edu.kettering.mapsdemo.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>
[/code]

Getting Ready to Use Google Maps Android API v2

Why do we need another tutorial for Google Maps Android API v2? I have discovered little things are missed or inaccurate in tutorials here and there (even in Google’s developer guideline). I do not want to repeat every single detail that you can find other places. This can be a supplementary material for Google’s developer guide for Google Maps Android API v2.

We know what the Google Maps is already. Also the 2nd version was introduced many months ago. Google Maps API in Android was also improved and named v2. Many things have  changed since last year.

Let’s get started. I am assuming we are using Eclipse as an IDE.

Install Google Play services SDK

To use Google Maps in Android we should have Google Play services. I don’t know why Google uses the name “Play” for Maps services. Anyway…

  • Start the Android SDK Manager.
  • Find Google Play services in the Extras.
  • Install the package by clicking “Install …” button.

Get the library for Google Play services

After the package is installed. We have to make the library usable for other projects.

  • Import the library so that my project can use it.
    • Go to File > Import > Android > Existing Android Code … and click Next.
    • Browse and find “<your android sdk folder>/extras/google/google_play_services/libproject/google-play-services_lib” and click Finish.
  • We just installed Google Play services library.

Make the sample app, maps work.

There are few samples in the Google Play services SDK. Let us make “maps” work. We could use this as a working template that can be utilized for future projects.

  • Import the sample.
    • Go to File > Import > Android > Existing Android Code … and click Next.
    • Browse and find “<your android sdk folder>/extras/google/google_play_services/samples/maps”.
    • The default new project name of the sample is “MainActivity.” This is not a smart choice at all. Let us change it to something more meaningful such as “MapsSample” before you click the Finish button.
    • Also make sure that you check “Copy projects into workspace” so that the original code is intact.
  • Well.. you can see tons of errors. Look hopeless. But do not worry. We will fix them shortly.
    • Go to Project > Properties.
    • Find Android in the left. You will see the Library pane in your right. If you see the ‘X’ mark in red, select it and click Remove.
    • Click Add… and select the “google-play-services_lib” item. Click OK. Now you can see the check mark in green.
  • Most errors should be gone now. RetainMapActivity has some errors that are from using “FragmentActivity.”
    • Fragment was introduced in Android 3.0 (API level 11). ADT (Build: v21.1.0-569685) makes templates using minSDK 8. The example was written using Support Lib anyway. Let us use the support library.
  • Add a support lib v4 into the project.
    • Make the “libs” folder inside the project folder. If you followed my recommendation in naming the project, the folder name is “MapsSample” and the “libs” folder must be inside the folder.
    • Find “android-support-v4.jar” at “<your android sdk folder>/extras/android/support/v4/” and copy it into the “libs” folder.
    • Go to Project > Properties.
    • Find “Java Build Path” in the left. Select the “Libraries” tab and click “Add External JARs…” Find the “android-support-v4.jar” file. Note: Do not select the jar file inside the Android SDK folder.
    • This must remove all remaining errors.
  • Run the app. You may see the program crashes.
    • Go to Project > Properties.
    • Find “Java Build Path” in the left. Select the “Libraries” tab.  Find the “android-support-v4.jar” file and remove it. I know, I know.. This is a strange step. But it should fix the crash.
  • If you still see errors from GoogleMap related packages and classes, just choose “Fix project setup..” from the Quick Fix suggestion and select “Add archive ‘google-play-services.jar – ….” and click OK. This will add “google-play-services.jar” into the build path.

Emulator

As of writing this Android emulator does not support Google Play services. We should use an actual Android device.

API Key

An API Key is required to use Google Play services.  To get a key we need an SHA-1 fingerprint and the application registration with the Google Maps Android API v2.

SHA-1 fingerprint

  • Locate debug.keysotre file in the “.android” in the current user folder.
    • /Users/&lt;user name&gt;/.android/ or ~/.android/
  • List the SJA-1 fingerprint.
    • keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
  • Find the “SHA1:” line in the output.
    • Alias name: androiddebugkeyCreation date: Apr 4, 2013
      Entry type: PrivateKeyEntry
      Certificate chain length: 1
      Certificate[1]:
      Owner: CN=Android Debug, O=Android, C=US
      Issuer: CN=Android Debug, O=Android, C=US
      Serial number: 515de791
      Valid from: Thu Apr 04 16:50:25 EDT 2013 until: Sat Mar 28 16:50:25 EDT 2043
      Certificate fingerprints:
      MD5: 11:22:33:44:A8:0E:99:00:33:94:44:33:55:7E:66:FD
      SHA1: <span style="color:#ff0000">FF:CC:BB:16:99:E3:AA:FF:55:44:42:77:AE:55:46:99:43:55:88:C2</span>
      Signature algorithm name: SHA1withRSA
      Version: 3
    • Copy the hexa-decimal string after “SHA1:” (Note that the string above is not actual fingerprint)

Registration

  • Go to https://code.google.com/apis/console/
  • Select “Services” and find “Google Maps Android API v2” in the middle of the list.
    • Turn the switch on.
  • Select API Access.
    • Click “Create new Android key…”
    • Paste the copied SHA-1 fingerprint and put ‘;’ followed by the package name (com.example.mapdemo).
  • Find “API key:” in the “Key for Android apps (with certificates)”

Put the Key into AndroidManifest.xml

Locate AndroidManifest.xml and open it. Find “YOUR_OWN_KEY” and replace it with the API key.

[code language=”xml”]
<application
android:icon="@drawable/ic_launcher"
android:label="@string/demo_title"
android:hardwareAccelerated="true">
<meta-data
android:name="com.google.android.maps.v2.API_KEY"
android:value="YOUR_OWN_KEY"/>
[/code]

Connect your Android device and execute the sample. You will see “Google Maps API Demos” app.