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:
- Install Android Studio.
- 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.
- 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.
- Add the required settings to your application's manifest.
- 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
- Enable billing on your project. For details, see create a billing account.
- In the Cloud Console, enable the Maps SDK for Android on your project. For details, see enable APIs.
- 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:
android.permission.INTERNET
- Used by the API to download map tiles from Google Maps servers.android.permission.ACCESS_NETWORK_STATE
- Allows the API to check the connection status in order to determine whether data can be downloaded.
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.