Google Maps Android API v2

Google Maps Android API Utility Setup

This page describes how to set up the Google Maps Android API utility library with Eclipse, and to run the demo app included in the library.

For guidelines on setting up the Google Maps Android API utility library with Android Studio/Gradle or Maven, please refer to the library's website.

  1. Prerequisites and notes
  2. Install the Android SDK
  3. Get the Google Maps Android API utility library
  4. Import the utility library into Eclipse
  5. Import the Google Play services SDK
  6. Add the Android Support Library
  7. Run the utility demo app on your Android device

Prerequisites and notes

The Google Maps Android API utility library supports Android API level 8 and above. The animated re-clustering features are only available for Android API level 14 and above. When setting your project build target, make sure you use the latest Android API level.

Throughout the setup procedure described below, it's a good idea to clean and build the projects often, to make sure you don't try to fix errors that are already fixed. To be on the safe side, use Project > Clean > Clean all projects after each step. Also, make sure Project > Build Automatically is checked.

Install the Android SDK

Install the Android SDK. Note that the ADT Bundle includes a version of Eclipse with the Android Developer Tools (ADT) built in.

Get the Google Maps Android API utility library

Download the android-maps-utils repository. You can do it by cloning the repo (recommended, to receive automatic updates) or downloading a zip file. If you want to customize the library, you should fork the repo.

The repository includes:

  • A demo application, in the demo directory.
  • The library of utilities, in the library directory.
  • Various files containing license, contributors, and readme information.
  • Gradle build configuration, for use with Android Studio.

Import the utility library into Eclipse

Follow these steps to import the demo and library directories from the utility library into Eclipse:

  1. Choose File > Import > Android > Existing Android Code Into Workspace, and click Next.
  2. Browse to the location where you saved the Google Maps Android API Utility Library, select the option to Copy projects into workspace, and import the demo and library directories.
Importing the demo and library directories
Importing the utility library

Hint: Eclipse will show errors on your project at this stage. Don't be discouraged. The next steps will fix the errors.

Import the Google Play services SDK

The Google Maps Android API v2 is distributed as part of the Google Play services SDK. You can download the Google Play services SDK via the Android SDK Manager.

Here is a summary of the steps you will need to take:

  1. Install the Google Play services SDK and import it into Eclipse, as described in the Google Play services documentation.
  2. Mark Google Play services as a library: Right-click the google-play-services_lib project, and choose Properties > Android. Tick the Is Library option.
    Properties of the Google Play services library after import
    Properties of the Google Play services library
  3. Follow the above steps to mark the utility library project as a library too.
  4. Reference the Google Play services library as a dependency for the utility library project: Right-click the library project and choose Properties > Android. Follow the steps in Referencing a Library Project.
    Properties of the utility library
    Properties of the utility library

Add the Android Support Library

Now you need to add the Android Support library to the utility library project:

  1. Right-click the library project and choose Android Tools > Add support library.
  2. Accept the license and install the library.

Run the utility demo app on your Android device

The utility library ships with a demo app that includes sample implementations of each utility. Follow these steps to run the demo app on your Android device.

Reference the utility library from the utility demo app

Add the utility library as a dependency of the utility demo app:

  1. Right-click the MainActivity project (this is the utility demo app) and choose Properties > Java Build Path.
  2. Click the Projects tab and choose Add.
  3. Select the library project and click OK, then OK again.
Properties of the utility demo app
Properties of the utility demo app

Get an API key

To access the Google Maps servers with the Google Maps Android API, you need to add an API key to your application. The key is free, and it supports an unlimited number of users. To get a Maps API key, visit the Google APIs Console and provide the utility demo app's signing certificate and package name (com.google.maps.android.utils.demo).

Then add the API key to the utility demo app's AndroidManifest.xml file. Note that the demo app already has an API key in the manifest. You will need to replace the key with your own API key.

Detailed instructions are in the getting-started guide.

Run the demo app

If you haven't already done so, enable developer mode on the Android device. Then attach the Android device to your computer. Note that you cannot use the emulator for running Google Maps Android API v2.

Right click the MainActivity project (this is the utility demo app) and choose Run As > Android Application.

The app should open on the Android device. You can also find it in your app list, under the name Maps Utils Demo.

This screenshot shows the app on an Nexus 4 device:

The utility demo app on a Nexus 4

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.