Set up an Android Studio project

This page describes how to configure an Android Studio project to use the Maps SDK for Android without using the Google Maps template that is detailed in the Quickstart.

The Google Maps template automatically configures and adds a basic map to a new Android Studio project. However, you can also add a map to an Android project that uses a different Android Studio template. To do so, you need to manually configure your project and then add the map.

Step 1: Set up Android Studio

Android Studio Arctic Fox or later is required. If you haven't already done so, download and install it.
Ensure that you are using the Android Gradle plugin version 7.0 or later in Android Studio.

Step 2. Set up the SDK

The Maps SDK for Android library is available through Google's Maven repository. To add the SDK to your app, do the following:

In your top-level settings.gradle file, include the Gradle plugin portal, Google Maven repository, and Maven central repository under the pluginManagement block. The pluginManagement block must appear before any other statements in the script.
```
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
} 
```

In your top-level settings.gradle file, include the Google's Maven repository and Maven central repository under the dependencyResolutionManagement block:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

In your module-level build.gradle file, add the Google Play services dependency for the Maps SDK for Android.
```
dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.0.2'
    // ...
} 
```
In your module-level build.gradle file, set compileSdk and minSdk to the following values:
Note: Ensure that compileSdk is set to 31 or higher and minSdk is set to 19 or higher.
```
android {
    compileSdk 31

    defaultConfig {
        minSdk 19
        // ...
    }
```

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 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, we recommend that you use the Secrets Gradle Plugin for Android. To install the plugin and store your API key:

In Android Studio, open your project-level build.gradle file and add the following code to the dependencies element under buildscript.
```
plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
```
Next, open your module-level build.gradle file and add the following code to the plugins element.
```
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
    
```
Save the file and sync your project with Gradle.
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
    
```
Save the file.
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.

Step 4: Update the app manifest

This section describes the settings to add to your AndroidManifest.xml file.

Google Play services version number

Add the following declaration within the application element. This embeds the version of Google Play services that the app was compiled with.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Location permission

If your app needs to access the user's location, you need to request the location permission in your AndroidManifest.xml file. The options are ACCESS_FINE_LOCATION, which provides the precise user location, and ACCESS_COARSE_LOCATION, which is less precise. For details, see the location data guide.

To request the ACCESS_FINE_LOCATION permission, add this code to the manifest element:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

External storage permission

If you're targeting version 8.3 or later of the Google Play services SDK, you don't need the WRITE_EXTERNAL_STORAGE permission. If you're targeting earlier versions of the Google Play services SDK, you must request the WRITE_EXTERNAL_STORAGE permission, in the manifest element.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Apache HTTP Legacy library

If you are using com.google.android.gms:play-services-maps:16.0.0 or below and your app is targeting API level 28 (Android 9.0) or above, you must include the following declaration within the <application> element of AndroidManifest.xml. Otherwise, skip this declaration.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Step 5: 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:

Next steps

Once your project is configured, you can add a map.