# android-maps-utils: What the Kotlin Rewrite Changed for Android Map Developers

> The Maps SDK for Android Utility Library is now a set of focused Kotlin modules covering clustering, heatmaps, KML and GeoJSON import, marker animation and spherical geometry. It is worth adopting if you already build on Google Maps, and it is not a mapping engine of its own.

**googlemaps/android-maps-utils** — Maps SDK for Android Utility Library

- Repository: https://github.com/googlemaps/android-maps-utils
- Website: https://developers.google.com/maps/documentation/android-sdk/utility
- Stars: 3,622 · Forks: 1,553
- Language: Kotlin
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/googlemaps-android-maps-utils

## Who android-maps-utils is actually for

This library does not draw maps. It is a set of utilities that sit on top of the Google Maps SDK for Android, and every one of them assumes you already have a MapView or SupportMapFragment working. The README lists what the utilities do: marker animation, marker clustering for large numbers of points, text on marker icons, heatmaps, KML import, GeoJSON import and styling, polyline encoding and decoding, spherical geometry such as computeDistance, computeHeading and computeArea, and a Street View metadata check for whether a panorama exists at a location.

The audience is narrow and specific. You are building an Android app, you have signed up with Google Maps Platform, you have a project with the Maps SDK for Android enabled, and you have an API key associated with that project. If any of those is missing, the library will not help you, because it is not a replacement for the SDK. Teams that want a map renderer without Google Play Services should look elsewhere; nothing in this repository offers that.

## The Kotlin rewrite and the submodule split

As of version 5.0.0 the library was rewritten in Kotlin and split into focused submodules so you can depend only on what you need. That is the single most consequential change in the project's recent history, and the README points 4.x users at MIGRATION.md rather than pretending the upgrade is mechanical.

The split maps roughly onto function. android-maps-utils-core holds base utilities: PolyUtil, SphericalUtil, collection managers and Street View metadata. android-maps-utils-clustering holds marker clustering. android-maps-utils-data holds KML and GeoJSON import. android-maps-utils-heatmaps holds heatmaps. android-maps-utils-ui holds marker icons and animation. The aggregator artifact com.google.maps.android:android-maps-utils transitively pulls in all of them.

Note the repository layout: clustering/, collections/, data/, heatmaps/, ui/, library/ and maps-utils/ all exist as top-level directories, alongside bom/, build-logic/ and lint-checks/. That structure is consistent with the module story in the README, and it is also a hint about maintenance cost. If you depend on the aggregator, you take every submodule whether you use it or not. If you depend on individual submodules, you own the version alignment yourself, which is exactly what a BOM is for. The README documents the aggregator and the individual artifacts, but it does not spell out the BOM coordinates in the excerpt available here, so verify those before you build a dependency-management strategy around them.

## Installing android-maps-utils and drawing a first clustered map

The README gives two dependency styles. The simplest is the aggregator, which requires Google Play Services. It also notes that you do not need a separate dependency for the Maps SDK for Android, because the library builds in the compatible version of the SDK.

```kotlin
dependencies {
    implementation("com.google.maps.android:android-maps-utils:5.2.0")
}
```

If you would rather not pull in everything, the README shows the per-submodule form. Here is the core module, which is where PolyUtil and SphericalUtil live.

```kotlin
dependencies {
    implementation("com.google.maps.android:android-maps-utils-core:5.2.0")
    implementation("com.google.maps.android:android-maps-utils-clustering:5.2.0")
}
```

The README also documents a compatibility constraint that bites people integrating the Google Navigation SDK for Android: you must exclude the transitive play-services-maps dependency to prevent duplicate class conflicts.

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

For a working reference rather than a snippet, the repository ships a demo app. The README's steps are: clone the repository, add a secrets.properties file in the root project (not under version control), and add the keys. MAPS_API_KEY is required and must have the Maps SDK for Android enabled. PLACES_API_KEY is optional and needed for demos using the Places API, such as heatmaps with Places. MAP_ID is optional and needed for demos using Advanced Markers or Cloud-based Map Styling.

```properties
MAPS_API_KEY=YOUR_MAPS_API_KEY
PLACES_API_KEY=YOUR_PLACES_API_KEY
MAP_ID=YOUR_MAP_ID
```

Then build and run the debug variant. The README also allows setting the Map ID in demo/src/main/res/values/strings.xml as a map_id string, or hardcoding it in an XML layout with the map:mapId attribute. Requirements are Android API level 23 or higher.

## Where android-maps-utils stops helping

The library is stable and the last push was on 2026-09-23, but the release picture is worth reading carefully. v5.2.0 shipped on 2026-09-01, and v6.0.0-rc04 shipped on 2026-09-15. If you want the newest behaviour, you are choosing between a stable 5.x line and release candidates. The README's install snippets still reference 5.2.0, so the documented path is the stable one.

There are harder boundaries. The library requires Google Play Services through the Maps SDK for Android, which rules it out for devices or builds without them. It requires a Google Maps Platform project and an API key, so it is not usable offline or without a billing relationship with Google. The Navigation SDK integration needs the exclusion above or you get duplicate class conflicts, which is a build failure rather than a graceful degradation.

One more thing the README does not document: rollback. There is a MIGRATION.md for moving from 4.x to 5.x, but nothing in the excerpt describes reverting a version bump or what happens to persisted state when you do. Treat version changes here as something to test rather than assume.

## android-maps-utils versus Maps Compose and the raw SDK

The obvious alternative is the Maps SDK for Android on its own. The difference is not rendering, since both use the same map. It is that the SDK gives you markers, polylines and ground overlays, and leaves clustering, heatmap rendering, KML parsing and spherical math to you. android-maps-utils packages those as library code you call instead of algorithms you write and test.

The second alternative is Maps Compose, the Jetpack Compose wrapper for the Maps SDK. That is a different axis: it changes how you declare a map in a Compose UI, not what utilities exist. The README notes that Kotlin extensions for this library live in Maps Android KTX, which is where you go if you want idiomatic Kotlin call sites rather than the Java-shaped API. Choosing between these is not either/or. A Compose app can use Maps Compose for the map surface and android-maps-utils for clustering and geometry, and the per-submodule split makes that cheaper than it used to be, because you can take clustering without taking KML parsing.

## Licence and upgrade cost

The licence is Apache-2.0, which is permissive and standard for a Google-published utility library. That matters for redistribution: you can ship it inside a closed-source app. It does not change your obligations under Google Maps Platform terms, which govern the API key and the SDK usage separately from this repository's code licence. Nothing here is legal advice; check the terms that apply to your Maps Platform project.

Upgrade cost is the more practical concern. The 4.x to 5.x move is a rewrite plus a module split, and the repository maintains MIGRATION.md precisely because that is not a drop-in change. If you are on 4.x, budget for import changes and dependency changes together. If you are already on 5.x, the 5.2.0 to 6.0.0 path runs through release candidates, and the README does not describe what changed between them in the excerpt available here, so read CHANGELOG.md before you move. The presence of release-please-config.json and .release-please-manifest.json at the repository root suggests releases are automated, which usually means changelog entries are generated rather than hand-written. That helps, but it does not replace reading them.

## Conclusion

Adopt it if your Android app already depends on the Maps SDK for Android and you need clustering, heatmaps, KML or GeoJSON import, or spherical geometry rather than writing those yourself. Do not adopt it as a mapping engine: it renders nothing on its own, needs a Google Maps Platform project with the Maps SDK for Android enabled and an API key, and excludes nothing for you if you also integrate the Navigation SDK. Before committing, check which submodule actually holds the classes you need, confirm whether you want the 5.2.0 aggregator or the 6.0.0 release candidates, and verify that your API key configuration matches the sample app's secrets.properties setup.

## FAQ

### What is android-maps-utils and what does it do?

It is an open-source utility library for apps using the Google Maps SDK for Android. It provides marker animation, marker clustering, marker icons with text, heatmaps, KML and GeoJSON import, polyline encoding and decoding, spherical geometry helpers, and a Street View metadata check.

### How do I add android-maps-utils to my Android project?

Add the aggregator artifact com.google.maps.android:android-maps-utils to your dependencies, or depend only on the submodules you need such as android-maps-utils-core, android-maps-utils-clustering, android-maps-utils-data, android-maps-utils-heatmaps and android-maps-utils-ui. The library builds in a compatible version of the Maps SDK for Android, so you do not add a separate dependency for it.

### What are the requirements for using android-maps-utils?

Android API level 23 or higher, a Google Maps Platform project with the Maps SDK for Android enabled, and an API key associated with that project. The aggregator artifact requires Google Play Services.

### Does android-maps-utils work with the Google Navigation SDK for Android?

Yes, but the README states you must exclude the transitive play-services-maps dependency to prevent duplicate class conflicts. The documented exclusion targets configurations whose name contains navigation and excludes the group com.google.android.gms and module play-services-maps.

### Which version of android-maps-utils should I use?

The README's install snippets reference 5.2.0, which is the documented stable path. v6.0.0 release candidates exist, with v6.0.0-rc04 published on 2026-09-15, but the README does not describe the differences, so check CHANGELOG.md before moving to them.

## Sources

- [googlemaps/android-maps-utils on GitHub](https://github.com/googlemaps/android-maps-utils)
- [License: Apache-2.0](https://github.com/googlemaps/android-maps-utils/blob/main/LICENSE)
- [Project website](https://developers.google.com/maps/documentation/android-sdk/utility)
- [README](https://github.com/googlemaps/android-maps-utils/blob/main/README.md)
- [Releases](https://github.com/googlemaps/android-maps-utils/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googlemaps-android-maps-utils