Note: The Google Maps Platform Premium Plan is no longer available for sign up or new customers.
Your Google Maps Platform Premium Plan license provides enhanced support for the Maps SDK for Android. This document tells you how to create an Android app that uses the Maps SDK for Android with the Premium Plan.
Overview
Follow the instructions on this page to download the SDK, set up your project, and add a map. Here is a summary of the steps required:
- Download the SDK.
- Add the SDK to a new or existing Android project.
- Add your API key to the app manifest.
- Specify the required Android permissions and OpenGL ES version 2.
- Add a map.
Download the SDK
You can download the SDK as a static library or use the Android SDK Manager.
Option 1: Download the SDK as a static library
Download the latest release as a static library.
Option 2: Download the SDK using the Android SDK Manager
In Android Studio:
- Select Tools > Android > SDK Manager.
- Select Appearance & Behavior > System Settings > Android SDK.
- Click the SDK Update Sites tab.
- Click the plus (+) icon to add a new site.
- Enter a name, such as 'Google Maps for Work', and the URL:
https://dl.google.com/geosdk/android-m4b-addon.xml
- Click OK.
- Click the SDK Tools tab.
- Select Google Maps Mobile SDK for Work and click OK to complete the download.
Android Studio installs the library at
<android-sdk-folder>/extras/google/maps_for_business_sdk/
.
See the guide to the Android SDK Manager for instructions on using the Android SDK Manager as a stand-alone tool.
Add the SDK to your project
Below are the instructions for Android Studio. If you're using a different tool, see the instructions in the Android documentation for command line usage.
The Maps SDK for Android for the Premium Plan
is available in two formats: an aar
bundle (google-maps-sdk-m4b.aar
) and a
library module (google-maps-sdk-m4b_lib
). You can choose the format that suits
you best.
Option 1: Import the SDK from the aar bundle
Follow these steps in to include the aar
bundle (google-maps-sdk-m4b.aar
)
in your Android Studio project:
Browse to the Google Maps Platform Premium Plan at this location:
<android-sdk>/extras/google/maps_for_business_sdk
Copy the
google-maps-sdk-m4b.aar
file into thelibs
directory in your project. (Create the directory if it doesn't exist.)Add the following code in your app's
build.gradle
file:dependencies { implementation(name:'google-maps-sdk-m4b', ext:'aar') implementation 'com.android.support:support-v4:+' implementation 'com.android.support:appcompat-v7:+' implementation 'com.google.android.gms:play-services-basement:15.0.1' implementation 'com.google.android.gms:play-services-base:15.0.1' } repositories { flatDir{ dirs 'libs' } }
In your app's
build.gradle
file setcompileSdkVersion
to the latest version.Complete the configuration steps as described below.
Option 2: Import the SDK as a library module
Instead of using the aar
file, you can follow these steps to add the SDK
library module (google-maps-sdk-m4b_lib
) to an existing project in Android
Studio:
- In Android Studio, choose the option to import a new module (File -> New -> Import Module).
Browse to the SDK at this location:
<android-sdk>/extras/google/maps_for_business_sdk
Select the
google-maps-sdk-m4b_lib
directory, and click Choose.Accept the default values in the import wizard.
Click Finish. You'll see a text file summarising the results of the import process.
Make sure the library is included in the
settings.gradle
file:include ':googlemapssdkm4b_lib'
Add the following code in your app's
build.gradle
file:dependencies { implementation project(':googlemapssdkm4b_lib') implementation 'com.android.support:support-v4:+' implementation 'com.android.support:appcompat-v7:+' implementation 'com.google.android.gms:play-services-basement:15.0.1' implementation 'com.google.android.gms:play-services-base:15.0.1' }
In your app's
build.gradle
file setcompileSdkVersion
to the latest version.
Convert any existing configurations that use Google Play services
- If you have an existing app using Google Play services,
replace all references to the
com.google.android.gms.maps
package withcom.google.android.m4b.maps
. - Prefix all references to the XML layout attributes with
m4b_
. For example:m4b_mapType
andm4b_cameraZoom
.
Specify settings in the app manifest
An Android app that uses the Maps SDK for Android needs to specify
the following settings in its manifest file, AndroidManifest.xml
:
API key
Generate an API key for your project and add the key to AndroidManifest.xml
,
as described in the authentication guide.
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.
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.
Add a map
The easiest way to test that your app is configured correctly is to add a simple map.
In
activity_main.xml
, add the following fragment.<?xml version="1.0" encoding="utf-8"?> <fragment xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/map" android:layout_width="match_parent" android:layout_height="match_parent" android:name="com.google.android.m4b.maps.MapFragment"/>
In
MainActivity.java
, add the following code.package com.example.mapdemo; import android.app.Activity; import android.os.Bundle; public class MainActivity extends Activity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); } }
Build and run your app
Build and run your app. You should see a map.
Troubleshooting:
If you don't see a map, confirm that you've completed all of the steps appearing earlier in this document. In particular, make sure that your API key is correct and that that your account is enabled for the Google Maps Platform Premium Plan service.
If the number of methods in your project goes over the limit, you may receive an error:
Unable to execute dex: method ID not in [0, 0xffff]: 65536
For information on causes and solutions, see the Android developers' guide to building apps with over 65K methods.
If your project already depends on Guava you may receive class collision errors such as this one:
com.android.dex.DexException: Multiple dex files define Lcom/google/common/annotations/Beta
To solve this problem, you can delete the copy of Guava from the
google-maps-sdk-m4b_lib/libs
directory.
More information
How to migrate an existing app
The Android API available with the Premium Plan has been designed to be very similar to the standard Maps SDK for Android. Consequently, the migration process is straightforward.
- Download the Maps SDK for Android for the Premium Plan, and add the SDK to your project as described above.
- Replace all references to the
com.google.android.gms.maps
package withcom.google.android.m4b.maps
. - Prefix all references to the XML layout attributes with
m4b_
. For example:m4b_mapType
andm4b_cameraZoom
. - Generate a new API key for your project and add the key to
AndroidManifest.xml
, as described in the authentication guide. - Build your app.
Comparing versions
The following table describes the key differences between the using standard Maps SDK for Android and using the API with the Premium Plan.
Standard Maps SDK for Android | Premium Plan | |
---|---|---|
Package name | com.google.android.gms.maps |
com.google.android.m4b.maps |
XML attributes in layout file | Use the attribute name without a prefix. For example:
mapType . |
Prefix all attribute names with m4b_ . For example:
m4b_mapType . For details, see
the
documentation on XML attributes. |
Download location | Included with Google Play services. | Available as a static library. |
Support channels | Community based support | Access to Premium support |
Terms | Subject to the Google Maps Platform Terms of Service. | Subject to Google Maps Platform Premium Plan terms. |
Google Play services
The standard Maps SDK for Android requires both the
Google Play services APK and the Google Play services maps
client library
(com.google.android.gms:play-services-maps
). When used with the
Google Maps Platform Premium Plan, however, the SDK only requires that the Google
Play services APK is installed on the target device - the maps
client library
is not required.
When migrating your application to the Premium Plan,
you should remove the maps
client library from your project, along with any
references to the com.google.android.gms.maps
package. Please ensure that you
use only the Premium Plan SDK (the
com.google.android.m4b.maps
package) to access Maps.
You can freely include other Google Play services client libraries, to take advantage of other Google APIs, such as Google Analytics or Google Location and Activity Recognition.
Sample code
The Google Maps repo on GitHub includes a number of samples
illustrating the use of the Maps SDK for Android in your Android app.
Note that the sample apps use the com.google.android.gms.maps
package, not
the com.google.android.m4b.maps
used with the
Premium Plan.
The sample apps also require the Google Play services SDK,
as they use the Location APIs for parts of the demo.
In addition, you can find code snippets on each page of the developer's guide.
Documentation
The main source of information about the Google Maps Platform Premium Plan is the developer and reference documentation available elsewhere on our site.