Google Maps Android v1 API (Deprecated)

Google Maps Android v1 API - External Library

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, 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:

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 targets to 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 command 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 manifest file.

For more information about working with Android projects, see Developing on Eclipse with ADT on the Android Developers site.

For more information about API Levels and how to use them, see Android API Levels and the documentation for the <uses-sdk> manifest element.

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 Manager.

  1. Click the "New" button to begin creating a new AVD.
  2. 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:minSdkVersion attribute in your application's manifest, as described above.
  3. 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 android:name attribute whose value is com.google.android.maps. Here's an example:

<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>

The <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:

<sdk>/add-ons/google_apis-<api-level>/samples/MapsDemo

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.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.