Existing Project Configuration

This page describes how to configure an existing Android project to use the Maps SDK for Android if you're using a project type other than a Google Maps project. To create a new app that uses the Google Maps project type, see Get Started.

Overview

The overall process of adding a map to an Android application is as follows:

  1. Install Android Studio.
  2. Install and configure the Google Play services SDK, which includes the Maps SDK for Android. Note: If you use the Maps SDK for Android with a Google Maps Platform Premium Plan license, you must download and configure the Premium Plan SDK instead.
  3. Get an API key. To do this, you will need to register a project in the Google Cloud Console, create an API key, and restrict the API key using your app's signing certificate.
  4. Add the required settings to your application's manifest.
  5. Add the Maps dependency to your app-level build.gradle file.

Below are more details about each step in the process.

Download Android Studio

Follow the guides to download and install Android Studio.

Install the Google Play services SDK

You need an Android project for your app, to complete the steps in this section. If you haven't yet created an Android application, you can follow the guide to creating a 'hello world' app. See Creating an Android Project.

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

For detailed instructions, see the Google Play services documentation.

Get a Google Maps API key

  1. Enable billing on your project. For details, see create a billing account.
  2. In the Cloud Console, enable the Maps SDK for Android on your project. For details, see enable APIs.
  3. Follow the Get an API Key guide to get, add, and restrict an API key.

Add the required settings to your app's manifest

Edit your application's AndroidManifest.xml file and add the following settings.

Specify the Google Play services version number

Add the following declaration within the <application> element of AndroidManifest.xml. This embeds the version of Google Play services that the app was compiled with.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Specify your API key

Ensure you include your API key in the AndroidManifest.xml file, as described in the Get an API Key guide.

Specify Android permissions

Specify the permissions your application needs, by adding <uses-permission> elements as children of the <manifest> element in AndroidManifest.xml.

Location permissions

If your application accesses the user's current location by enabling the My Location layer, you must request location permissions as described in the guide to location data.

External storage permission

If you're targeting version 8.3 or later of the Google Play services SDK, you no longer need the WRITE_EXTERNAL_STORAGE permission to use the Maps SDK for Android.

If you're targeting earlier versions of the Google Play services SDK, you must request the android.permission.WRITE_EXTERNAL_STORAGE permission.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Note: If your app is targeting API level 23 (Android 6.0), which requires the use of runtime permissions, you should target version 8.3 or later of the Google Play services SDK.

Permissions automatically merged into your manifest

The following permissions are defined in the Google Play services manifest, and are automatically merged into your app's manifest at build time. You don't need to add them explicitly to your manifest:

Specify requirement for OpenGL ES version 2

The Maps SDK for Android uses OpenGL ES version 2 to render the map. The following setting is defined in the Google Play services manifest, and is automatically merged into your app's manifest at build time. You don't need to add it explicitly to your manifest:

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

This notifies external services of the requirement. In particular, it prevents Google Play Store from displaying your app on devices that don't support OpenGL ES version 2.

Specify requirement for Apache HTTP Legacy library

If you are using com.google.android.gms:play-services-maps:16.0.0 or below and your app is targeting API level 28 (Android 9.0) or above, you must include the following declaration within the <application> element of AndroidManifest.xml.

  <uses-library
      android:name="org.apache.http.legacy"
      android:required="false" />

This is handled for you if you are using com.google.android.gms:play-services-maps:16.1.0 and is not necessary if your app is targeting a lower API level.

Add the Maps dependency

In your app-level build.gradle file, add the Maps dependency:

dependencies {
    implementation 'com.google.android.gms:play-services-maps:17.0.0'
    // ...
}

Next steps

Once your project is configured, you can add a map.