Create an Android app that displays a map by using the Google Maps Views template for Android Studio. If you have an existing Android Studio project that you'd like to set up, see [Set up an Android Studio project](https://developers.google.com/maps/documentation/android-sdk/config.md.txt). > [!NOTE] > **Note:** This quickstart uses the **Google Maps Views Activity** template, which creates an XML layout with a [`SupportMapFragment`](https://developers.google.com/android/reference/com/google/android/gms/maps/SupportMapFragment.md.txt). If you're building your UI with Jetpack Compose, see the [Maps Compose library](https://developers.google.com/maps/documentation/android-sdk/maps-compose.md.txt) instead. This quickstart is intended for developers who are familiar with basic Android development with Kotlin or Java. ## About the development environment We recommend using the latest stable version of [Android Studio](https://developer.android.com/studio/install.html) and the [Android Gradle plugin](https://developer.android.com/build/releases/gradle-plugin). > [!NOTE] > **Note:** If your development environment uses a different version of Android Studio or Gradle, you might have to modify the steps based on your environment. For more information about Android Studio and Gradle versions, see [Android Gradle plugin and Android Studio compatibility](https://developer.android.com/build/releases/about-agp#android_gradle_plugin_and_android_studio_compatibility). ## 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 6.0 or higher and includes the Google APIs. - To use an Android device, follow the instructions at [Run apps on a hardware device](https://developer.android.com/studio/run/device.html). - To use an Android emulator, you can create a virtual device and install the emulator by using the [Device Manager](https://developer.android.com/studio/run/managing-avds.html) that comes with Android Studio. > [!NOTE] > **Note:** If you choose to use an Android emulator, ensure that you choose a device profile with the Google Play icon, ![The Google Play icon.](https://developers.google.com/static/maps/documentation/android-sdk/images/play-icon.png), displayed in the **Play** column. This icon indicates that these profiles are fully [CTS](https://source.android.com/compatibility/cts) compliant and can use system images that include the Play Store app: ![The Add Device dialog in Android Studio showing Phone profiles such as Pixel 10 with the Google Play icon in the Play column.](https://developers.google.com/static/maps/documentation/android-sdk/images/play-store-icon-emulator.png) The **Add Device** dialog in Android Studio Device Manager showing virtual device profiles with the Google Play icon in the **Play** column. ## Create a Google Maps project in Android Studio 1. Open Android Studio, and click **New Project** in the **Welcome to Android Studio** window. 2. In the **New Project** window, under the **Phone and Tablet** category, select **No Activity** , and then click **Next**. > [!NOTE] > **Note:** If you start from the default **Empty Activity** (Jetpack Compose) template instead of **No Activity** and later add a **Google Maps Views > Activity** , `MapsActivity` (`AppCompatActivity`) crashes on launch with `IllegalStateException: You need to use a Theme.AppCompat theme (or > descendant) with this activity` because the Compose template sets the theme parent in `res/values/themes.xml` to `android:Theme.Material.Light.NoActionBar`. To avoid this crash, update your theme's `parent` in `res/values/themes.xml` to `Theme.AppCompat.DayNight.NoActionBar` and ensure that `.MapsActivity` is configured as the `MAIN`/`LAUNCHER` activity in `AndroidManifest.xml`. 3. Complete the **New Project** 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](https://developer.android.com/kotlin). - Set **Minimum SDK** to an SDK version compatible with your test device. You must select a version greater than the minimum version required by the Maps SDK for Android version 20.0.x, which is Android API Level 23 ("Marshmallow"; Android 6.0) or higher. See the [Release Notes](https://developers.google.com/maps/documentation/android-sdk/release-notes.md.txt) for the latest information on the SDK version requirements. > [!NOTE] > **Note:** If you are unsure of what SDK version to choose, select the **Help me choose** link to display distribution information for supported Android SDKs. For example, if you choose **Android API Level 23 ("Marshmallow"; Android 6.0)**, your app should run on over 99% of Android devices. - Set the **Build configuration language** to Kotlin DSL or Groovy DSL. Snippets for both build configuration languages are shown in the following procedures. 4. Click **Finish**. Android Studio starts Gradle and builds the project. This may take some time. 5. Add the **Google Maps Views Activity**: 1. Right-click on the `app` folder in your project. 2. Select **New \> Google \> Google Maps Views Activity**: ![The Android Studio context menu for the app folder showing New, Google, and Google Maps Views Activity selected.](https://developers.google.com/static/maps/documentation/android-sdk/images/add-maps-activity.png) Adding a **Google Maps Views Activity** from the `app` context menu in Android Studio. 3. In the **New Android Activity** dialog box, select the **Launcher Activity** checkbox. 4. Select **Finish**. For more information, see [Add code from a template](https://developer.android.com/studio/projects/templates). 6. When the build is finished, Android Studio opens the `AndroidManifest.xml` and `MapsActivity` files. Your activity can have a different name, depending on what you configured during setup. > [!CAUTION] > **Caution:** The project generated by the **Google Maps Views Activity** template won't run without additional configuration. Although the template adds the Secrets Gradle Plugin for Android to `libs.versions.toml` and `build.gradle.kts`, it doesn't configure `secrets.properties` and instead places a `YOUR_API_KEY` placeholder directly in `AndroidManifest.xml` (with legacy comments referencing `local.properties`). **Don't paste your API key > directly into `AndroidManifest.xml` or add it to `local.properties`.** Instead, follow the instructions in [Set up your Google Cloud project](https://developers.google.com/maps/documentation/android-sdk/start.md.txt#get-key) and [Add the API key to your app](https://developers.google.com/maps/documentation/android-sdk/start.md.txt#add-key) to store `MAPS_API_KEY` in a `secrets.properties` file, configure the `secrets` block in your module-level Gradle file, and set `android:value="${MAPS_API_KEY}"` in `AndroidManifest.xml`. ## Set up your Google Cloud project Complete the following required Cloud console setup steps: ### Step 1: Set up your project #### Console [Video](https://www.youtube.com/watch?v=uINleRduCWM) 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](https://console.cloud.google.com/projectselector2/home/dashboard?utm_source=Docs_NewProject&utm_content=Docs_Central) 2. Make sure that billing is enabled for your Cloud project. [Confirm that billing is enabled for your project](https://console.cloud.google.com/project/_/billing?utm_source=Docs_Billing&utm_content=Docs_Central). Google Cloud offers a $0.00 charge trial. The trial expires at the end of 90 days or after the account has accrued $300 worth of charges, whichever comes first. Cancel anytime. For more information, see [Billing account credits](https://developers.google.com/maps/billing-credits) and [Billing](https://developers.google.com/maps/billing-and-pricing/billing). #### Cloud SDK ```bash gcloud projects create "PROJECT" ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud projects create`](https://cloud.google.com/sdk/gcloud/reference/projects/create) > [!NOTE] > **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: Enable APIs or SDKs 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](https://console.cloud.google.com/apis/library/maps-android-backend.googleapis.com?utm_source=Docs_EnableAPIs&utm_content=Docs_maps-android-backend) #### Cloud SDK ```bash gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com" ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud services enable`](https://cloud.google.com/sdk/gcloud/reference/services/enable) - [`gcloud services disable`](https://cloud.google.com/sdk/gcloud/reference/services/disable) ### Step 3: Get an API key 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 a new key or add an API or SDK to an existing key, follow these instructions. #### Console 1. Go to the **Google Maps Platform \> Keys \& Credentials** page. [Go to the Keys \& Credentials page](https://console.cloud.google.com/projectselector/google/maps-apis/credentials?utm_source=Docs_CreateAPIKey&utm_content=Docs_maps-android-backend) 2. If prompted, select your project. 3. Do one of the following: - **Create a new key**: 1. Click **Create credentials \> API key**. 2. In the **Create API key** panel, open the **Select API restrictions** list. 3. Clear any APIs that this key doesn't need, and make sure **Maps SDK for Android** stays selected. 4. Click **Create**. The panel displays your new API key. - **Use an existing key**: 1. Click the name of the key. 2. In the **Select API restrictions** list, select **Maps SDK for Android**. 3. Click **Save**. Selecting an API here doesn't enable it. Make sure Maps SDK for Android is enabled on its [API Library page](https://console.cloud.google.com/apis/library/maps-android-backend.googleapis.com). 4. To see the key string later, go to the **Keys \& Credentials** page and click **Show key** for the key. If the console looks different from these steps, see [Create an API key](https://cloud.google.com/docs/authentication/api-keys#create) and [Add API restrictions](https://cloud.google.com/docs/authentication/api-keys#adding-api-restrictions) in the Google Cloud documentation. #### Cloud SDK Replace PROJECT_ID with your project ID in the following commands. - **Create a new key** : Run the following command, and replace DISPLAY_NAME with a name for the key. ```bash gcloud services api-keys create \ --project="PROJECT_ID" \ --display-name="DISPLAY_NAME" \ --api-target=service=maps-android-backend.googleapis.com ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud services api-keys create`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/create) - **Use an existing key** : Run the following command, and replace KEY_ID with the ID of the key. The `--append` flag keeps the APIs that the key already allows. Without it, the command replaces them. ```bash gcloud services api-keys update KEY_ID \ --project="PROJECT_ID" \ --append \ --api-target=service=maps-android-backend.googleapis.com ``` Read more about the [Google Cloud SDK](https://cloud.google.com/sdk), [Cloud SDK installation](https://cloud.google.com/sdk/docs/install), and the following commands: - [`gcloud services api-keys update`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/update) - [`gcloud services api-keys list`](https://cloud.google.com/sdk/gcloud/reference/services/api-keys/list) The key ID isn't the key string or display name. To find it, run `gcloud services api-keys list --project="PROJECT_ID"`. The ID is the last part of the `name` field: `projects/PROJECT_NUMBER/locations/global/keys/KEY_ID`. To see the key string, run `gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID"`. ## Add the API key to your app This section describes how to store your API key so that it can be securely referenced by your app. You shouldn't check your API key into your version control system, so we recommend storing it in a `secrets.properties` file in the root directory of your project and excluding that file from version control. For more information about Gradle properties files, see [Gradle properties files](https://developer.android.com/studio/build#properties-files). To simplify this task, we recommend that you use the [Secrets Gradle Plugin for Android](https://github.com/google/secrets-gradle-plugin). To install the Secrets Gradle Plugin for Android and store your API key: 1. In Android Studio, open your top-level `build.gradle.kts` or `build.gradle` file and add the following code to the `plugins` block. ### Kotlin ```kotlin plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false } ``` ### Groovy ```groovy plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false } ``` 2. Open your module-level `build.gradle.kts` or `build.gradle` file and add the following code to the `plugins` element. ### Kotlin ```kotlin plugins { id("com.android.application") // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") } ``` ### Groovy ```groovy plugins { id 'com.android.application' // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' } ``` 3. If you use Android Studio, [sync your project with Gradle](https://developer.android.com/studio/build#sync-files). 4. Open the `secrets.properties` file in your top-level directory, and then add the following code. Replace `YOUR_API_KEY` with your API key. Make sure to add `secrets.properties` to your `.gitignore` file (or otherwise exclude it from your version control system) so that you don't check your API key into version control. > [!NOTE] > **Note:** If the `secrets.properties` file doesn't exist, create it in the same folder as the `local.properties` file. ``` MAPS_API_KEY=YOUR_API_KEY ``` 5. Create the `local.defaults.properties` file in your top-level directory, the same folder as the `secrets.properties` file, and then add the following code. > [!NOTE] > **Note:** Enter the code as shown. Don't replace `DEFAULT_API_KEY` with your API key. ``` MAPS_API_KEY=DEFAULT_API_KEY ``` The purpose of this file is to provide a backup location for the API key if the `secrets.properties` file isn't found so that builds don't fail. This can happen if you clone the app from a version control system that omits `secrets.properties` and you haven't yet created a `secrets.properties` file locally to provide your API key. 6. In your `AndroidManifest.xml` file, go to `com.google.android.geo.API_KEY` and update the `android:value` attribute as follows: ```html ``` **Note:** `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. 7. In Android Studio, open your module-level `build.gradle.kts` or `build.gradle` file and edit the `secrets` property. If the `secrets` property doesn't exist, add it. Edit the properties of the plugin to set `propertiesFileName` to `"secrets.properties"`, set `defaultPropertiesFileName` to `"local.defaults.properties"`, and set any other properties. ### Kotlin ```kotlin secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file). // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" } ``` ### Groovy ```groovy secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file). // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" } ``` > [!NOTE] > **Note:** If Logcat reports `E/Google Maps Android API: Authorization failure` or map tiles fail to load, verify that **Maps SDK for Android** is enabled in your Google Cloud project, that the API key in your merged `AndroidManifest.xml` is valid, and that if your API key uses [Android app > restrictions](https://developers.google.com/maps/documentation/android-sdk/get-api-key), your project's package name (such as `com.example.myfirstmapsapp`) and the SHA-1 fingerprint of your signing keystore (such as `~/.android/debug.keystore`) are added to the API key's allowed Android applications in Google Cloud. ## 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](https://developer.android.com/guide/components/activities/intro-activities) 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`](https://developers.google.com/android/reference/com/google/android/gms/maps/SupportMapFragment.md.txt) object manages the lifecycle of the map and is the parent element of the app's UI. - The [`GoogleMap`](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap.md.txt) object provides access to the map data and view. This is the main class of the Maps SDK for Android. The [Map Objects](https://developers.google.com/maps/documentation/android-sdk/map.md.txt) guide describes the [`SupportMapFragment`](https://developers.google.com/android/reference/com/google/android/gms/maps/SupportMapFragment.md.txt) and [`GoogleMap`](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap.md.txt) objects in more detail. - The [`moveCamera`](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap.md.txt#moveCamera(com.google.android.gms.maps.CameraUpdate)) function centers the map at the [`LatLng`](https://developers.google.com/android/reference/com/google/android/gms/maps/model/LatLng.md.txt) 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](https://developers.google.com/maps/documentation/android-sdk/views.md.txt) guide for details. - The [`addMarker`](https://developers.google.com/android/reference/com/google/android/gms/maps/GoogleMap.md.txt#addMarker(com.google.android.gms.maps.model.MarkerOptions)) function adds a marker to the coordinates for Sydney. See the [Markers](https://developers.google.com/maps/documentation/android-sdk/marker.md.txt) guide for details. ### Kotlin ```kotlin // Add a marker in Sydney and move the camera val sydney = LatLng(-34.0, 151.0) map.addMarker( MarkerOptions() .position(sydney) .title("Marker in Sydney"), ) map.moveCamera(CameraUpdateFactory.newLatLng(sydney)) ``` ### Java ```java // Add a marker in Sydney and move the camera LatLng sydney = new LatLng(-34, 151); map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney")); map.moveCamera(CameraUpdateFactory.newLatLng(sydney)); ```
### Module Gradle file The module-level `build.gradle.kts` or `build.gradle` file includes the following Maps dependency, which is required by the Maps SDK for Android. ### Kotlin ```kotlin dependencies { // Maps SDK for Android implementation(libs.play.services.maps) } ``` ### Groovy ```groovy dependencies { // Maps SDK for Android implementation "com.google.android.gms:play-services-maps:20.0.0" } ``` If your project uses a Gradle version catalog (`gradle/libs.versions.toml`), define the `play-services-maps` dependency in `libs.versions.toml`: ```toml [versions] play-services-maps = "20.0.0" [libraries] play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" } ``` > [!NOTE] > **Note:** The exact version can change based on the current version of the Maps SDK for Android. To learn more about managing the Maps dependency, see [Versioning](https://developers.google.com/maps/documentation/android-sdk/versions.md.txt). ### XML layout file The `activity_maps.xml` file is the [XML layout file](https://developer.android.com/guide/topics/ui/declaring-layout) 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`](https://developer.android.com/studio/write/tool-attributes#toolscontext) sets the default activity of the fragment to `MapsActivity`, which is defined in the maps activity file. - [`android:name`](https://developer.android.com/guide/fragments/create#add-xml) sets the class name of the fragment to [`SupportMapFragment`](https://developers.google.com/android/reference/com/google/android/gms/maps/SupportMapFragment.md.txt), which is the fragment type used in the maps activity file. The XML layout file contains the following code: ## Deploy and run the app ![Screenshot with the map and marker centered on Sydney, Australia.](https://developers.google.com/static/maps/documentation/android-sdk/images/quickstart-map.png) When you run the app successfully, it displays a map centered on Sydney, Australia with a marker on the city, as shown in the 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](https://developers.google.com/maps/documentation/android-sdk/configure-map.md.txt): This document 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)](https://developers.google.com/codelabs/maps-platform/maps-platform-101-android#0): This codelab walks you through an app that demonstrates some additional features of the Maps SDK for Android. - [Use the Maps Android KTX library](https://developers.google.com/maps/documentation/android-sdk/ktx.md.txt): This Kotlin extensions (KTX) library lets you take advantage of several Kotlin language features while using the Maps SDK for Android.