Note: Version 1 of the Google Maps Android API was officially deprecated on December 3rd, 2012. It is no longer possible to create an API key, which is required to use the API; however, existing keys will continue to work. Existing and new developers are encouraged to use Google Maps Android API v2.
Version 1 of the Google Maps Android API includes a Maps external library,
com.google.android.maps. The classes of the Maps library offer
built-in downloading, rendering, and caching of Maps tiles, as well as a
variety of display options and controls.
The key class in the Maps library is
MapView, a subclass of
ViewGroup in the Android standard library. A MapView displays a
map with data obtained from the Google Maps service. When the MapView has focus, it can
capture keypresses and touch gestures to pan and zoom the map automatically,
including handling network requests for additional maps tiles. It also provides
all of the UI elements necessary for users to control the map. Your application
can also use MapView class methods to control the MapView programmatically and
draw a number of Overlay types on top of the map.
In general, the MapView class provides a wrapper around the Google Maps API that lets your application manipulate Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views.
The Maps external library is not part of the standard Android library, so it may not be present on some compliant Android-powered devices. Similarly, the Maps external library is not included in the standard Android library provided in the SDK. The Google APIs add-on provides the Maps library to you so that you can develop, build, and run maps-based applications in the Android SDK, with full access to Google Maps data.
To use the classes of the Maps external library in your application, you need to:
- Install the Google APIs add-on, as described in the Installing document.
- Configure your project to build against the installed Google APIs add-on.
- Set up an Android Virtual Device configuration that uses a the Google APIs add-on.
- Add a uses-library element to your application's manifest file, to reference the Maps library.
- Use the Maps classes in your application.
- Add your Google Maps Android API v1 Key to your application so that your application can display data from the Google Maps service.
- Sign your application properly, using the certificate that matches your API Key.
The sections below provide more information.
The Javadoc reference for the Google Maps Android API v1 is available for download
Setting up a Maps Project
Once you've installed the Google APIs add-on, you can add Maps capabilities to any existing or new Android project. To give your application access to the Maps library, all you have to do is to set the project's properties so that the build tools can locate the Maps library in the Google APIs add-on. The process for doing that depends on whether you are developing in Eclipse with the ADT Plugin or developing using Ant.
Note that multiple versions of the Google APIs add-on are available,
each targeting a specific Android platform API Level. Select the version whose
API Level is appropriate for your application, based on the application's
android:minSdkVersion attribute, declared in the application's
For more information about working with Android projects, see Developing on Eclipse with ADT on the Android Developers site.
Setting up an AVD
Use the Android Virtual Device (AVD) Manager to configure one or more virtual devices which you'll be able to use with the Android Emulator when you build and run your app. Take note of the instructions for configuring virtual machine acceleration, which you should use with an x86 target AVD as described in the instructions. This will improve your experience with the emulator.
Referencing the Maps Library from the Application's Manifest File
To use the classes of the Maps external library in an application, you must
reference the library from the application's manifest file. Specifically, you
must add a
<uses-library> element as a child of the
<application> element, with an
attribute whose value is
com.google.android.maps. Here's an
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.package.name"> ... <application android:name="MyApplication" > <uses-library android:name="com.google.android.maps" /> ... </application> ... </manifest>
<uses-library> reference is required, because it
enables the build tools to link your application against the Maps external
library. It also ensures that the Android system will not install your
application on a device unless the required library is available.
Using the Maps Classes in Your Application
The Maps library provides a variety of classes that let you display and
manipulate Google Maps data in your application. To get started, first take
a look at what's available in the
The key class in the library is
MapView, a subclass of
ViewGroup in the Android standard library. The MapView class displays
maps data from the Google Maps service and handles all of the
interaction with the service. It includes all of the UI elements necessary
for the user to control the map and also provides methods that let
your application manipulate the map, draw overlays, and so on.
To use Maps in your application, extend the MapActivity class and then create a layout that includes a MapView element.
Getting a Google Maps Android API v1 Key
Important: It is not possible to create a new Key for the Google Maps Android v1 API; however, existing keys will continue to work.
Signing Your Application with the Proper Certificate
The final step to enable the display of Maps data is to sign your application with the proper certificate. The certificate you use to sign your application must match the certificate that is associated with the API Key in your MapView objects. For example:
- If your MapView objects reference an API Key that you obtained by registering the debug certificate, then you must sign your application with the debug certificate.
- If you want to sign your application for release, your MapView objects must reference an API Key that you obtained by registering your release certificate.
The Maps service allows your MapView objects to download data only if they identify themselves with an API Key that is registered to the application's signer certificate. For this reason, remember that you must update the Maps API Key referenced by your MapView objects whenever you change signing certificates.