Maps SDK for Android Quickstart

Create an Android app that displays a map by using the Google Maps template for Android Studio. If you have an existing Android Studio project that you'd like to set up, see Project Configuration.

This quickstart is intended for developers who are familiar with basic Android development with Java or Kotlin.

Set up the development environment

1. Android Studio is required. If you haven't already done so, download and install it.

2. Add the Google Play services SDK to Android Studio. The Maps SDK for Android is distributed as part of the Google Play services SDK, which you can add through the SDK Manager.

Set up an Android device

To run an app that uses the Maps SDK for Android, you must deploy it to an Android device or Android emulator that is based on Android 4.0 or higher and includes the Google APIs.

• To use an Android device, follow the instructions at Run apps on a hardware device.
• To use an Android emulator, you can create a virtual device and install the emulator by using the Android Virtual Device (AVD) Manager that comes with Android Studio.
  Note: If you choose to use an Android emulator, ensure that you choose a device with the Play icon, , displayed under the Play Store column. This icon indicates that these profiles are fully CTS compliant and may use system images that include the Play Store app:

  

Create a Google Maps project

1. Open Android Studio, and click Create New Project in the Welcome to Android Studio window.

2. In the New Project window, under the Phone and Tablet category, select the Google Maps Activity, and then click Next.

3. Complete the Google Maps Activity form:

   • Set Language to Java or Kotlin. Both languages are fully supported by the Maps SDK for Android. To learn more about Kotlin, see Develop Android apps with Kotlin.

   • Set Minimum SDK to an Android SDK version that is supported by your test device.

4. Click Finish.

When you finish creating your project, Android Studio will start Gradle and build the project. This may take some time. When the build is finished, Android Studio will open the google_maps_api.xml and MapsActivity files. Your activity may have a different name, but it will be the one you configured during setup.

For more information about creating a project, see Create an Android Project.

The google_maps_api.xml file contains instructions on getting a Google Maps API key and then adding it to the file. Do not add your API key to the file. Doing so stores your API key less securely. Instead, follow the instructions in the next section.

Set up in Cloud Console

Complete the required Cloud Console setup steps by clicking through the following tabs:

Step 1

Console

1. In the Google Cloud Console, on the project selector page, click Create Project to begin creating a new Cloud project.

   Go to the project selector page

2. Make sure that billing is enabled for your Cloud project. Confirm that billing is enabled for your project.

   Google Cloud offers a $300 free trial, and Google Maps Platform features a recurring $200 monthly credit. For more information, see Billing account credits and Billing.

Cloud SDK

gcloud projects create "PROJECT"

Read more about the Google Cloud SDK , Cloud SDK installation , and the following commands:

• gcloud projects create

Note: If you don't plan to keep the resources that you create in a learning exercise, create a project instead of selecting an existing project. After you finish the exercise, you can delete the project, removing all resources associated with the project.

Step 2

To use Google Maps Platform, you must enable the APIs or SDKs you plan to use with your project.

Console

Enable the Maps SDK for Android

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Read more about the Google Cloud SDK , Cloud SDK installation , and the following commands:

• gcloud services enable
• gcloud services disable

Step 3

This step only goes through the API Key creation process. If you use your API Key in production, we strongly recommend that you restrict your API key. You can find more information in the product-specific Using API Keys page.

The API key is a unique identifier that authenticates requests associated with your project for usage and billing purposes. You must have at least one API key associated with your project.

To create an API key:

Console

1. Go to the Google Maps Platform > Credentials page.

   Go to the Credentials page

2. On the Credentials page, click Create credentials > API key.
   The API key created dialog displays your newly created API key.
3. Click Close.
   The new API key is listed on the Credentials page under API keys.
   (Remember to restrict the API key before using it in production.)

Cloud SDK

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Read more about the Google Cloud SDK , Cloud SDK installation , and the following commands:

• gcloud alpha services api-keys create

Add the API key to your app

This section describes how to store your API key so that it can be more securely referenced by your app. You should not check your API key into your version control system, so we recommend storing it in the local.properties file, which is located in the root directory of your project. For more information about the local.properties file, see Gradle properties files.

To streamline this task, you can use the Secrets Gradle Plugin for Android.

To install the plugin and store your API key:

1. In Android Studio, open your root-level build.gradle file and add the following code to the dependencies element under buildscript.

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
       }
   }
       

2. Next, open your app-level build.gradle file and add the following code to the plugins element.

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. Save the file and sync your project with Gradle.
4. Open the local.properties in your project level directory, and then add the following code. Replace YOUR_API_KEY with your API key.

   MAPS_API_KEY=YOUR_API_KEY
       

5. Save the file and sync your project with Gradle.
6. In your AndroidManifest.xml file, go to com.google.android.geo.API_KEY and update the android:value attribute as follows:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

Note: As shown above, com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

Look at the code

Examine the code supplied by the template. In particular, look at the following files in your Android Studio project.

Maps activity file

The maps activity file is the main activity for the app, and contains the code to manage and display the map. By default, the file that defines the activity is named MapsActivity.java or if you set Kotlin as the language for your app, MapsActivity.kt.

The main elements of the maps activity:

• The SupportMapFragment object manages the life cycle of the map and is the parent element of the app's UI.

• The GoogleMap object provides access to the map data and view. This is the main class of the Maps SDK for Android. The Map Objects guide describes the SupportMapFragment and GoogleMap objects in more detail.

• The moveCamera function centers the map at the LatLng coordinates for Sydney Australia. The first settings to configure when adding a map are usually the map location and camera settings; such as viewing angle, map orientation, and zoom level. See the Camera and View guide for details.

• The addMarker function adds a marker to the coordinates for Sydney. See the Markers guide for details.

The maps activity file contains the following code:

Java

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

App-level Gradle file

The app-level build.gradle file includes the following maps dependency, which is required by the Maps SDK for Android.

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

To learn more about managing the Maps dependency, see Versioning.

XML layout file

The activity_maps.xml file is the XML layout file that defines the structure of the app's UI. The file is located in the res/layout directory. The activity_maps.xml file declares a fragment that includes the following elements:

• tools:context sets the default activity of the fragment to MapsActivity, which is defined in the maps activity file.
• android:name sets the class name of the fragment to SupportMapFragment, which is the fragment type used in the maps activity file.

The XML layout file contains the following code:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

Deploy and run the app

When you run the app successfully, it will display a map that is centered on Sydney Australia with a marker on the city as seen in the following screenshot.

To deploy and run the app:

1. In Android Studio, click the Run menu option (or the play button icon) to run your app.
2. When prompted to choose a device, choose one of the following options:
   • Select the Android device that's connected to your computer.
   • Alternatively, select the Launch emulator radio button and choose the virtual device that you set up.
3. Click OK. Android Studio will start Gradle to build your app, and then display the results on your device or emulator. It can take several minutes before the app launches.

Next steps

• Set up a map: This topic describes how to set up the initial and runtime settings for your map, such as the camera position, map type, UI components, and gestures.

• Add a map to your Android app (Kotlin): This codelab walks you through an app that demonstrates some additional features of the Maps SDK for Android.

• Use the Maps Android KTX library: This Kotlin extensions (KTX) library allows you to take advantage of several Kotlin language features while using the Maps SDK for Android.