> [!WARNING] > **NOTICE:** Version 2.0.0 and later of the Places SDK for Android is dependent on [AndroidX](https://developer.android.com/jetpack/androidx). Beginning with this version, the old support library will no longer be supported. In order to retain compatibility, you must migrate your projects to use AndroidX. To configure your app to use the Places SDK for Android, follow these steps. They are required for all apps using the Places SDK for Android. ## Step 1: Set up Android Studio This document describes a development environment using [Android Studio Hedgehog](https://developer.android.com/studio/install.html) and the [Android Gradle plugin](https://developer.android.com/build/releases/gradle-plugin) version 8.2. > [!NOTE] > **Note:** If your development environment uses a different version of Android Studio or Gradle you might have to modify the steps based on those versions. For more information about Android Studio and Gradle versions, see [Android Gradle plugin and Android Studio compatibility](https://developer.android.com/build/releases/gradle-plugin#android_gradle_plugin_and_android_studio_compatibility). ## Step 2. Set up the SDK The Places SDK for Android library is available through [Google's Maven repository](https://maven.google.com/). To add the SDK to your app, do the following: 1. In your top-level `settings.gradle.kts` file, include the [Gradle plugin portal](https://plugins.gradle.org/), [Google Maven repository](https://maven.google.com/web/index.html), and [Maven central repository](https://search.maven.org/artifact) under the `pluginManagement` block. The `pluginManagement` block must appear before any other statements in the script. ```yaml pluginManagement { repositories { google() mavenCentral() gradlePluginPortal() } } ``` 2. In your top-level `settings.gradle.kts` file, include the [Google's Maven repository](https://maven.google.com/web/index.html) and [Maven central repository](https://search.maven.org/artifact) under the `dependencyResolutionManagement` block: ```yaml dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { google() mavenCentral() } } ``` 3. In the `dependencies` section of your **module** -level `build.gradle.kts` file, add a dependency to the Places SDK for Android: > [!NOTE] > **Note:** Places SDK for Android version 3.5.0 requires `kotlin-bom` 1.8.0 or later. For more information on the `kotlin-bom` dependency, see [Usage of the latest kotlin-stdlib version in transitive dependencies](https://kotlinlang.org/docs/whatsnew18.html#usage-of-the-latest-kotlin-stdlib-version-in-transitive-dependencies). ### Groovy ```groovy dependencies { implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version")) implementation("com.google.android.libraries.places:places:3.5.0") } ``` ### Kotlin ```kotlin dependencies { // Places and Maps SDKs implementation("com.google.android.libraries.places:places:6.0.2") } ``` 4. In your module-level `build.gradle.kts` file, set `compileSdk` and `minSdk` to the following values: > [!NOTE] > **Note:** Ensure that `compileSdk` is set to 34 or higher and `minSdk` is set to 23 or higher. ### Groovy ```groovy android { compileSdk 34 defaultConfig { minSdk 23 // ... } } ``` ### Kotlin ```kotlin android { compileSdk = 34 defaultConfig { minSdk = 23 // ... } } ``` 5. In the `buildFeatures` section of your module-level `build.gradle` file, add the `BuildConfig` class, which you use to access metadata values defined later in this procedure: ### Groovy ```groovy android { // ... buildFeatures { buildConfig true // ... } } ``` ### Kotlin ```kotlin android { // ... buildFeatures { buildConfig = true // ... } } ``` ## Step 3: Add your API key to the project 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. ``` PLACES_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. ``` PLACES_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 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" } ``` ## Step 4. Initialize the Places API client To initialize the Places SDK for Android within an activity or fragment, pass the API key when calling [`Places.initializeWithNewPlacesApiEnabled()`](https://developers.google.com/maps/documentation/places/android-sdk/reference/com/google/android/libraries/places/api/Places.md.txt#initializeWithNewPlacesApiEnabled(android.content.Context,%20java.lang.String)): ### Kotlin ```kotlin // Define a variable to hold the Places API key. val apiKey = BuildConfig.PLACES_API_KEY // Log an error if apiKey is not set. if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") { Log.e("Places test", "No api key") finish() return } // Initialize the SDK Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey) // Create a new PlacesClient instance val placesClient = Places.createClient(this) ``` ### Java ```java // Define a variable to hold the Places API key. String apiKey = BuildConfig.PLACES_API_KEY; // Log an error if apiKey is not set. if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) { Log.e("Places test", "No api key"); finish(); return; } // Initialize the SDK Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey); // Create a new PlacesClient instance PlacesClient placesClient = Places.createClient(this); ``` > [!WARNING] > **IMPORTANT:** Never add API keys directly to application code. In production environments, we recommend using a [secure mechanism](https://developers.google.com/maps/api-key-best-practices) to manage API keys. You are now ready to begin using the Places SDK for Android! ## Step 5: Set up an Android device To run an app that uses the Places 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. ## Next steps After your project is configured, you can explore the [sample apps](https://developers.google.com/maps/documentation/places/android-sdk/examples.md.txt).