Note: Version 1 of the Google Maps Android API has been officially deprecated as of December 3rd, 2012. This means that from March 18th, 2013 you will no longer be able to request an API key for this version. No new features will be added to Google Maps Android API v1. However, apps using v1 will continue to work on devices. Existing and new developers are encouraged to use Google Maps Android API v2.
To make it easier for you to add powerful mapping capabilities to your
application, the Google APIs add-on includes a Maps external library,
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. If you are using the Android SDK, you don't need to install the add-on — it's preinstalled in the SDK package.
- Set up a new Android project — or reconfigure an existing one — 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.
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.
Here's how to set the build target, if you are developing on Eclipse with ADT:
- If you want to add Maps to an existing application, right-click the project in Package Explorer, choose Properties > Android and then select a build target from the list displayed. You must choose the "Google APIs" build target.
- If you are creating a new Android project in Eclipse, the New Project Wizard will ask you to specify the build target for the application. You must choose the "Google APIs" build target.
If you are developing in Ant, you use the android tool included in the SDK to set the build target for your project:
- For an existing project, use the command
android list targetsto list the build targets available in your SDK. Locate the "Google APIs" target and note its ID. Then use the command
android update project --target <targetID> --path path/to/your/project/to set the project to use the Google APIs add-on target.
- For an new project, list the build targets as decribed above and use the
android create project --target <targetID> --path path/to/your/project/to set the project to use the Google APIs target.
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
After you've built your project, you need to be able to run, debug, profile, and test it. To run your Maps-based application in the Android Emulator, you need to set up an Android Virtual Device (AVD) that is configured to use the Google APIs add-on. To set up the AVD, use the Android AVD Manager.
Launch the AVD Manager by using the
android command without any
options. If you are developing in Eclipse/ADT, you can also access the tool from
Window > Android SDK and AVD
- Click the "New" button to begin creating a new AVD.
- In the dialog that appears, specify a name for the AVD and select the system
image target that you want the AVD to use. Select one of the
"Google APIs (Google Inc.)" targets, making sure to choose a version
whose API Level matches the
android:minSdkVersionattribute in your application's manifest, as described above.
- Configure the other options and then click "Create AVD".
Once you've finished creating the AVD, you can run it from the AVD Manager UI or you can use the emulator's command-line interface. If you are developing in Eclipse, you can configure a Run Configuration to start the AVD and install your application on it.
For more information about AVDs, see Android Virtual Devices on the Android Developers site.
If you have a physical device that runs the appropriate platform (as determined by its API Level) and includes the Maps external library, you can also run, debug, and test your application on the device, rather than in the emulator. For more information, see Developing on a Device.
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 com.google.android.maps package.
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. For a quick-start on how to set up a MapView, read the Hello, MapView tutorial on the Android Developers site.
If you'd like to look at sample code, the Google APIs add-on includes an example application called MapsDemo that you can load into your development environment and run. The application is located in the Google APIs directory:
Note that, in order for MapView objects to display data from the Google Maps service, you will need to include a Google Maps Android API key. Key registration is no longer available, but you can use an existing Google Maps Android API v1 Key.
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. The information in this section assumes that you have and existing application and key.
MapView objects display Maps tiles downloaded from the Google Maps service. Before you can use Google Maps data, you must register with the Maps service, agreeing to the Terms of Service and supplying an MD5 fingerprint of the certificate(s) that you will use to sign your application. For each registered certificate fingerprint, the service provides you with a Google Maps Android API v1 Key — an alphanumeric string that uniquely identifies you and your certificate. You then store your API Key in your MapView objects, so that when they request Maps data, the server can determine that you are registered with the service.
If you do not store a valid Google Maps Android API v1 Key in your MapView elements, you can still compile and run your application, but your MapView elements won't be able to display data from the Maps server.
Keep in mind that each Google Maps Android API v1 Key is uniquely associated with a specific signing certificate.
Signing Your Application with the Proper Certificate
If you have followed the steps in Obtaining a Google Maps Android API v1 Key, 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.