Maps SDK for Android Utility Library

Description

This open-source library contains utilities that are useful for a wide range of applications using the Google Maps SDK for Android.

As of version 5.0.0, the library has been rewritten in Kotlin and split into focused submodules so you can depend only on what you need. If you are upgrading from 4.x, see the migration guide.

• Marker animation - animates a marker from one position to another
• Marker clustering — handles the display of a large number of points
• Marker icons — display text on your Markers
• Heatmaps — display a large number of points as a heat map
• Import KML — displays KML data on the map
• Import GeoJSON — displays and styles GeoJSON data on the map
• Polyline encoding and decoding — compact encoding for paths, interoperability with Maps API web services
• Spherical geometry — for example: computeDistance, computeHeading, computeArea
• Street View metadata — checks if a Street View panorama exists at a given location
• Reactive Kotlin Extensions & Builders — coroutine suspensions (awaitMap()), reactive Flow observers (mapClickEvents()), and option builder DSLs (addMarker { ... }) consolidated directly into com.google.maps.android.*.

Important

KTX Consolidation Notice (v6.0.0+): All Kotlin extensions (maps-ktx and maps-utils-ktx from android-maps-ktx) are now built directly into android-maps-utils under the canonical com.google.maps.android.* packages. Separate dependencies on android-maps-ktx or maps-utils-ktx are no longer needed and should be removed. Legacy calls to com.google.maps.android.ktx.* packages remain supported via @Deprecated(level = DeprecationLevel.WARNING) bridges that forward directly to canonical implementations.

Requirements

• Android API level 23+
• Sign up with Google Maps Platform
• A Google Maps Platform project with the Maps SDK for Android enabled

• An API key associated with the project above ... follow the API key instructions if you're new to the process

Installation

dependencies {
    // Utilities and consolidated Kotlin Extensions for Maps SDK for Android
    // The aggregator artifact transitively pulls in all submodules below.
    implementation("com.google.maps.android:android-maps-utils:6.0.0") // x-release-please-version
}

Alternatively, depend only on the submodules your app needs:

dependencies {
    // Base utilities: PolyUtil, SphericalUtil, collection managers, Street View metadata
    implementation("com.google.maps.android:android-maps-utils-core:6.0.0") // x-release-please-version
    // Marker clustering
    implementation("com.google.maps.android:android-maps-utils-clustering:6.0.0") // x-release-please-version
    // KML and GeoJSON import
    implementation("com.google.maps.android:android-maps-utils-data:6.0.0") // x-release-please-version
    // Heatmaps
    implementation("com.google.maps.android:android-maps-utils-heatmaps:6.0.0") // x-release-please-version
    // Marker icons and animation
    implementation("com.google.maps.android:android-maps-utils-ui:6.0.0") // x-release-please-version
}

Compatibility with Google Navigation SDK for Android

If your project integrates the Google Navigation SDK for Android, you must exclude the transitive play-services-maps dependency to prevent duplicate class conflicts:

configurations.all {
    if (name.contains("navigation", ignoreCase = true)) {
        exclude(group = "com.google.android.gms", module = "play-services-maps")
    }
}

Sample App

This repository includes a sample app that illustrates the use of this library.

To run the demo app, ensure you've met the requirements above then:

1. Clone the repository

2. Add a file secrets.properties in the root project (this file should NOT be under version control to protect your API key)

3. Add the following keys to secrets.properties:

   • MAPS_API_KEY: Required. Your Google Maps API Key. Ensure it has the Maps SDK for Android enabled.
   • PLACES_API_KEY: Optional. Required for demos using the Places API (e.g., Heatmaps with Places). Ensure the Places API is enabled.
   • MAP_ID: Optional. Required for demos using Advanced Markers or Cloud-based Map Styling.

   For example:

   MAPS_API_KEY=YOUR_MAPS_API_KEY
   PLACES_API_KEY=YOUR_PLACES_API_KEY
   MAP_ID=YOUR_MAP_ID

4. Build and run the debug variant for the Maps SDK for Android version

Setting up the Map ID

Some of the features in the demo app, such as Advanced Markers, require a Map ID. You can learn more about map IDs in the official documentation. You can set the Map ID in one of the following ways:

1. secrets.properties: Add a line to your secrets.properties file with your Map ID:

   MAP_ID=YOUR_MAP_ID

2. strings.xml: Alternatively, you can set the Map ID in the demo/src/main/res/values/strings.xml file:

   <string name="map_id">YOUR_MAP_ID</string>

3. XML Layout Files: You can also hardcode the Map ID directly in the XML layout files where a map is defined, by setting the map:mapId attribute:

   <androidx.fragment.app.FragmentContainerView
       map:mapId="YOUR_MAP_ID" 
       />

Documentation

See the documentation for a full list of classes and their methods.

Full guides for using the utilities are published in Google Maps Platform documentation.

Usage

Marker utilities

Marker utilities

• Marker animation source, sample code
• Marker clustering source, guide
• Advanced Markers clustering source, sample code
• Marker icons source, sample code

Data visualization utilities

Data visualization utilities

• Display heat maps source, guide
• Import GeoJSON source, guide
• Import KML source, guide

Polyline and spherical geometry utilities

Additional utilities

• Polyline encoding and decoding source, encoding sample, decoding sample
• Spherical geometry source, compute distance sample

Reactive Kotlin Extensions & Builders (Consolidated in v6.0.0)

Reactive Kotlin Extensions & Builders

All Kotlin extensions formerly provided by android-maps-ktx (maps-ktx and maps-utils-ktx) are now integrated into android-maps-utils (v6.0.0+) under canonical packages (com.google.maps.android.*, com.google.maps.android.clustering.*, etc.).

1. Coroutine Suspensions (awaitMapsSdkInitialized(), awaitMap(), awaitAnimateCamera())

import com.google.android.gms.maps.MapsInitializer
import com.google.maps.android.awaitMapsSdkInitialized
import com.google.maps.android.awaitMap
import com.google.maps.android.awaitAnimateCamera

// Suspend until Maps SDK is initialized
val renderer: MapsInitializer.Renderer = context.awaitMapsSdkInitialized(MapsInitializer.Renderer.LATEST)

// Suspend until GoogleMap is ready on MapView / MapFragment
val googleMap: GoogleMap = mapView.awaitMap()

// Suspend until camera animation completes
googleMap.awaitAnimateCamera(CameraUpdateFactory.newLatLngZoom(sydney, 12f))

2. Option Builders DSL (addMarker, addPolyline, addPolygon)

import com.google.maps.android.addMarker
import com.google.maps.android.addCircle

googleMap.addMarker {
    position(LatLng(-33.852, 151.211))
    title("Sydney Opera House")
}

googleMap.addCircle {
    center(LatLng(-33.870, 151.200))
    radius(500.0)
    strokeWidth(2f)
}

3. Reactive Flow Observers (mapClickEvents, cameraMoveEvents)

import com.google.maps.android.mapClickEvents

lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        googleMap.mapClickEvents().collect { latLng ->
            Log.d("MapClick", "Clicked: $latLng")
        }
    }
}

Backward Compatibility & Deprecation

Existing references to com.google.maps.android.ktx.* continue to work through @Deprecated(level = DeprecationLevel.WARNING) forwarding wrappers. You can safely migrate your code incrementally to com.google.maps.android.*.

Street View metadata utility

Street View metadata utility

The StreetViewUtil class provides functionality to check whether a location is supported in StreetView. You can avoid errors when adding a Street View panorama to an Android app by calling this metadata utility and only adding a Street View panorama if the response is OK.

StreetViewUtils.fetchStreetViewData(LatLng(8.1425918, 11.5386121), BuildConfig.MAPS_API_KEY,Source.DEFAULT)

fetchStreetViewData will return NOT_FOUND, OK, ZERO_RESULTS or REQUEST_DENIED, depending on the response.

By default, the Source is set to Source.DEFAULT, but you can also specify Source.OUTDOOR to request outdoor Street View panoramas.

Internal usage attribution ID

This library calls the addInternalUsageAttributionId method, which helps Google understand which libraries and samples are helpful to developers and is optional. Instructions for opting out of the identifier are provided below.

If you wish to disable this, you can do so by removing the initializer in your AndroidManifest.xml using the tools:node="remove" attribute:

<provider
    android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    <meta-data
        android:name="com.google.maps.android.utils.attribution.AttributionIdInitializer"
        tools:node="remove" />
</provider>

Contributing

Contributions are welcome and encouraged! If you'd like to contribute, send us a pull request and refer to our code of conduct and contributing guide.

Using AI

This repository provides an official Gemini Skill and an llm-integration-prompt.md to help AI agents navigate the codebase and provide assistance. Refer to the contributing guide for more details on AI usage.

Terms of Service

This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform Terms of Service.

If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.

This library is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this library.

Support

This library is offered via an open source license. It is not governed by the Google Maps Platform Support Technical Support Services Guidelines, the SLA, or the Deprecation Policy. However, any Google Maps Platform services used by the library remain subject to the Google Maps Platform Terms of Service.

This library adheres to semantic versioning to indicate when backwards-incompatible changes are introduced. Accordingly, while the library is in version 0.x, backwards-incompatible changes may be introduced at any time.

If you find a bug, or have a feature request, please file an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of our developer community channels. If you'd like to contribute, please check the contributing guide.

You can also discuss this library on our Discord server.