Maps SDK for Android Utility Setup

Select platform: Android iOS

This page describes how to set up the Maps SDK for Android utility library, and to run the demo app included in the library.

Prerequisites and notes

The Maps SDK for Android utility library supports Android API level 15 and above. When setting your project build target, make sure you use the latest Android API level.

The reference documentation is available on GitHub.

Step 1. Install the Maps SDK for Android utility library

Add the following dependency to your app's build.gradle.kts file:

dependencies {


    // Utility Library for Maps SDK for Android
    // You do not need to add a separate dependency for the Maps SDK for Android
    // since this library builds in the compatible version of the Maps SDK.
    implementation("com.google.maps.android:android-maps-utils:3.8.2")
}

Use one of the utilities from the library, such as marker clustering, heatmaps, or the other utilities.

Step 2. (Optional) Install the Maps SDK for Android utility KTX library

The Maps SDK for Android utility library comes with a corresponding Kotlin extensions (KTX) library. This library provides Kotlin language features—such as extension functions, named and default arguments—to enable you to write concise and idiomatic Kotlin. If you are not developing in Kotlin, you can skip this step.

To use this library, add the following dependency, in addition to the android-maps-utils dependency, to your app's build.gradle.kts file:

dependencies {

    // KTX for the Maps SDK for Android Utility Library
    implementation("com.google.maps.android:maps-utils-ktx:5.1.1")
}

Check out the Maps KTX GitHub page for additional information about this library.

Step 3. View the Maps SDK for Android utility library source code

Since the utility library is open source, you can download the android-maps-utils library to your machine to customize it, view the demo app, or if you just want to understand how the library works. You can do so by cloning the repo (recommended, to receive automatic updates) or downloading a zip file. If you want to customize the library, you should fork the repo.

The repository includes:

  • A demo application, in the demo directory.
  • The library of utilities, in the library directory.
  • Various files containing license, contributors, and readme information.
  • Gradle build configuration, for use with Android Studio.

Run the utility demo app

The GitHub repository for the utility library ships with a demo app that includes sample implementations of each utility. Follow these steps to run the demo app on your Android device.

  1. Download the repository using one of the options mentioned above.
  2. In Android Studio, choose File -> New -> Import Project.
  3. Browse to and select (double-click) the android-maps-utils directory that was created when you cloned the utility library. Android Studio now builds the project.
  4. If you are using an Android device instead of an emulator, make sure to enable developer mode. Then attach the Android device to your computer.
  5. Add a single line to local.properties that looks like this:

    MAPS_API_KEY=YOUR_API_KEY

    Where YOUR_API_KEY is the API key you obtained as described in Using API Keys.

  6. Build and run the demo app.

The app should open on the Android device, displaying a list of utilities including clustering, poyutil, heatmap, and more. You can also find the app in your app list, under the name Maps Utils Demo.