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.
- Prerequisites and notes
- Install the Android SDK
- Get the Google Maps Android API utility library
- Import the utility library into Eclipse
- Import the Google Play services SDK
- Add the Android Support Library
- Run the utility demo app on your Android device
Prerequisites and notes
The Google Maps Android API utility library supports Android API level 9 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
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
- The library of utilities, in the
- 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
directories from the utility library into Eclipse:
- Choose File > Import > Android > Existing Android Code Into Workspace, and click Next.
- 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
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:
- Install the Google Play services SDK and import it into Eclipse, as described in the Google Play services documentation.
- Mark Google Play services as a library: Right-click the google-play-services_lib project, and choose Properties > Android. Tick the Is Library option.
- Follow the above steps to mark the utility library project as a library too.
- 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.
Add the Android Support Library
Now you need to add the Android Support library to the utility library project:
- Right-click the library project and choose Android Tools > Add support library.
- 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:
- Right-click the MainActivity project (this is the utility demo app) and choose Properties > Java Build Path.
- Click the Projects tab and choose Add.
- Select the library project and click OK, then OK again.
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 Developers Console
and provide the utility demo app's signing certificate and package
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
Detailed instructions are in the guide to API keys.
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.
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: