This page describes what you need to do to get set up to start building with the
Maps 3D SDK for Android. The setup process involves configuring a Google Cloud
project and API for use with the SDK, and then setting up an Android Studio
project. Complete these steps before [adding your first 3D map to your
app](https://developers.google.com/maps/documentation/maps-3d/android-sdk/add-a-3d-map).

## Prerequisites

To use the Maps 3D SDK for Android, your project and target devices must meet the
following requirements:

- **Minimum API level** : Android API level 24 (Android 7.0) or higher. Your app must target a `minSdk` of `24` or higher.
- **Google Play services** : The Maps 3D SDK for Android depends on [Google Play services](https://developers.google.com/android/guides/overview.md.txt). Target devices (and emulators with Google APIs) must have Google Play services installed.

## Set up a Google Cloud project and API key

Before you can start building with the Maps 3D SDK for Android, you need to set up a
Google Cloud project and API key to use with the Maps 3D SDK for Android by
completing the following 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.

Note that some integrations require you to enable multiple APIs/SDKs. If you are not sure which
APIs or SDKs to enable, try using
the [Capabilities Explorer](https://developers.google.com/maps/documentation/capabilities-explorer.md.txt), or consult the
documentation for the API/SDK you want to use.

To enable one or more APIs or SDKs:

#### Console

[Video](https://www.youtube.com/watch?v=n1UorU1PALk)

1. See the Google Maps Platform APIs and SDKs that you can enable by going to the Maps API
   Library page in the Cloud console:

   Go to the [Maps API Library
   page](https://console.cloud.google.com/project/_/google/maps-apis/api-list?utm_source=Docs_EnableAPIs&utm_content=Docs_Central)
2. Click the API or SDK you want to enable.
   - If the button says **ENABLE**, click the button to enable the API or SDK.
   - If the button says **MANAGE**, the API or SDK is already enabled and you don't need to do anything further.
   - Clicking either button will display the dashboard for the API or SDK. (Click the **DISABLE** button to remove the API or SDK from this project.)

#### Cloud SDK

The following command enables all of the Maps, Routes, and Places APIs:

```bash
gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-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)

Use this command to enable the Environment APIs:

```bash
gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"
```

> [!NOTE]
> **Note:** Enabling Places API also enables the Places Library, Maps JavaScript API, Places SDK for Android and Places SDK for iOS.

### 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_Central)
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 the APIs that you plan to use stay 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 the APIs that you plan to use.
     3. Click **Save**.

   Selecting an API here doesn't enable it. Make sure
   each API
   that you select is enabled in the
   [API Library](https://console.cloud.google.com/apis/library).
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 <var translate="no">PROJECT_ID</var> with your project ID in the following
commands.

- **Create a new key** : Run the following command, and
  replace <var translate="no">DISPLAY_NAME</var> with a name for the key.
  Replace <var translate="no">SERVICE_NAME</var> with the service
  name of an API that you plan to use, such as
  `places.googleapis.com`. To allow more APIs, repeat the
  `--api-target` flag.

  ```bash
  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=SERVICE_NAME
  ```

  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 <var translate="no">KEY_ID</var> with the ID of the key.
  Replace <var translate="no">SERVICE_NAME</var> with the service
  name of the API to add. 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=SERVICE_NAME
  ```

  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"`.

To enable the SDK, see the [Maps 3D SDK for Android](https://console.cloud.google.com/apis/library/mapsandroid.googleapis.com)
page in the Google Cloud console. For more information about completing these
steps, see [Getting started with the Google Maps Platform](https://developers.google.com/maps/get-started.md.txt).

## Set up an Android Studio project

This section explains how to create and configure an Android Studio project for
use with the Maps 3D SDK for Android.

### Part 1: Set up your project and Gradle configuration

1. Create a new Android Studio project using the **Empty Views Activity**
   template. In the project configuration, set **Minimum SDK** to
   **API 24** or higher.

2. If you are using Git for source control, modify the project `.gitignore`
   file to prevent your secrets file from being committed to version control:

   - In your project's root directory, open the `.gitignore` file.
   - Add the following line:

       secrets.properties

3. Update the project-level `build.gradle.kts` file:

   - In your project's root directory, open the `build.gradle.kts` file.
   - In the `plugins` block, add the Secrets Gradle plugin:

   ```kotlin
   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   ```
4. Update the `gradle/libs.versions.toml` file:

   - Open the `gradle/libs.versions.toml` file, which is usually located in the `gradle` directory within the project root directory.
   - In the `[versions]` section, add the versions for the SDK and Secrets Gradle plugin:

   ```toml
   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   ```
   - In the `[library]` section, add the SDK library:

   ```toml
   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   ```
   - In the `[plugins]` section, add the Secrets Gradle plugin:

   ```toml
   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   ```
5. Update the module-level `app/build.gradle.kts` file:

   - Open the module-level `build.gradle.kts` file, which is usually located within the `app` directory.
   - At the top of the file, add the Secrets Gradle plugin to the `plugins` block:

   ```kotlin
   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   ```
   - In the `dependencies` block, add the Google Play services dependency for the Maps 3D SDK for Android:

   ```kotlin
   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   ```
   - At the end of the file, outside of the `android` and `dependencies` blocks, add the secrets configuration:

   ```kotlin
   secrets {
       // Optionally specify a different filename containing your secrets.
       // The plugin defaults to "local.properties"
       propertiesFileName = "secrets.properties"

       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
   ```

### Part 2: Add your API key to your project

1. Create a `secrets.properties` file:

   - In the app module root directory (usually the `app` directory), create a new file named `secrets.properties`.
   - Add your API key to the file:

   ```properties
   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   ```

   > [!NOTE]
   > **Note:** Make sure you replace `YOUR_API_KEY_HERE` with the API key that you configured for use with the Maps 3D SDK for Android.

2. Create a `local.defaults.properties` file:
   - In the app module root directory, create a new file named
   `local.defaults.properties`.
   - Add a default or placeholder API key to the file. This file can be
   checked into version control:

   ```properties
   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   ```

### Part 3: Update your `AndroidManifest.xml` file

1. Open the `app/src/main/AndroidManifest.xml` file.

2. Inside the `<application>` tag, before the `<activity>` tag, add the
   following `<meta-data>` element to declare your API key:

   ```xml
   <application
       ...>

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

       <activity
           ...>
       </activity>
   </application>
   ```

   During the build process, the Secrets Gradle Plugin will replace the
   `${MAPS3D_API_KEY}` placeholder with the key from your `secrets.properties`
   file.

## Programmatic view initialization (optional)

If you prefer to initialize your map view programmatically rather than in XML
layouts, use
[`Map3DInitConfig`](https://developers.google.com/maps/documentation/maps-3d/android-sdk/reference/com/google/android/gms/maps3d/Map3DInitConfig.md.txt).

```kotlin
import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)
```

## Next steps

Now that you have a Google Cloud project, API key, and an Android Studio project
set up for use with the Maps 3D SDK for Android, you can [Add a 3D map to your
app](https://developers.google.com/maps/documentation/maps-3d/android-sdk/add-a-3d-map).