Get Started with Premium Plan on Android

Your Google Maps APIs Premium Plan license provides enhanced support for the Google Maps Android API. This document tells you how to create an Android app that uses the Google Maps Android API 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 Google Maps Android API 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 APIs Premium Plan at this location:

<android-sdk>/extras/google/maps_for_business_sdk
Copy the google-maps-sdk-m4b.aar file into the libs directory in your project. (Create the directory if it doesn't exist.)

Add the following code in your build.gradle file:

dependencies {
    compile(name:'google-maps-sdk-m4b', ext:'aar')

}

repositories {
    flatDir{
        dirs 'libs'
    }
}

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 a module dependency in your app's build.gradle file:

compile project(':googlemapssdkm4b_lib')

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 with com.google.android.m4b.maps.
Prefix all references to the XML layout attributes with m4b_. For example: m4b_mapType and m4b_cameraZoom.

Specify settings in the app manifest

An Android app that uses the Google Maps Android API 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 Google Maps Android API.

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 Google Maps Android API 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 APIs 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 Google Maps Android API. Consequently, the migration process is straightforward.

Download the Google Maps Android API 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 with com.google.android.m4b.maps.
Prefix all references to the XML layout attributes with m4b_. For example: m4b_mapType and m4b_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 Google Maps Android API and using the API with the Premium Plan.

	Standard Google Maps Android API	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 APIs Terms of Service.	Subject to Google Maps APIs Premium Plan terms.

Google Play services

The standard Google Maps Android API requires both the Google Play services APK and the Google Play services client library. When used with the Google Maps APIs Premium Plan, however, the SDK only requires that the Google Play services APK is installed on the target device - the client library is not required.

When migrating your application to the Premium Plan, you do not need to remove the Google Play services SDK from your project. However, you should remove any references to the com.google.android.gms.maps package. Google Play services contains a version of the Google Maps Android API as well as other Google services. If you make use of Play services within your app to use other Google APIs, please ensure that you use only the Premium Plan SDK (the com.google.android.m4b.maps package) to access Maps.

While the Google Play services client library is not required, you may find it helpful to include the library so that you can take advantage of other Google APIs, such as Google+ or the Location API.

Sample code

The Google Maps repo on GitHub includes a number of samples illustrating the use of the Google Maps Android API 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 APIs Premium Plan is the developer and reference documentation available elsewhere on our site.