google-maps-ios-utils: the geometry, heatmap and clustering helpers for Maps on iOS

The parts of a map app the SDK leaves to you

The Google Maps SDK for iOS Utility Library is an open source library of classes that are useful for a wide range of applications using the Maps SDK, and the feature list is the fastest way to see what it covers.

The geometry libraries are KML and GeoJSON rendering, which is how you get a file of places onto a map. The geometry utilities are the spherical geometry helper functions, which is the part you need when you are computing a distance or a bearing between two coordinates on a real globe rather than on a flat plane. Heatmaps are there, for showing density rather than individual points.

Then there is marker clustering, which handles the display of a large number of points. That is the feature most projects end up needing and most teams end up writing badly, because a map with ten thousand markers is unusable and a hand written clustering implementation is a weekend of work that then has to handle zoom changes, selection, and animation.

Marker customization is for displaying custom markers, and the quadtree data structure indexes two dimensional geometry points and performs two dimensional range queries, which is the data structure underneath the clustering rather than a separate feature.

So the library is best described as the set of things a mapping application needs beyond putting a map view on the screen. That is a good description of a companion library, and it is why the project exists as a separate repository with its own versioning and its own release cadence rather than as a folder inside the SDK.

The project is Apache 2.0 licensed, written primarily in Objective-C, and not archived, with the last push on 2026-10-16. The releases are v7.1.2 from that day, v7.1.1 from 2026-09-24, and v7.1.0 from 2026-01-21, and the documentation lives on the Google Maps Platform developer site.

Requirements, and the key you need first

The requirements are short and one of them is the one that trips people up.

You need iOS 16.0 or newer, and Xcode 15.0 or newer. You need the Maps SDK for iOS itself, and the releases page of this repository is where to find the minimum compatible version for a given release. And you need a Google Maps Platform API key from a project with the Maps SDK for iOS enabled.

That last one is a project setup step rather than a code change, and it has to be done before anything else works. The instructions for adding the key to your app are linked from the installation sections, and they are the same instructions whichever installation route you pick, because the key is registered against your bundle identifier in the Google Cloud console rather than in your project file.

The requirement list is worth reading as a compatibility statement rather than a checklist. The iOS 16 floor is the modern one for the SDK, and the Xcode floor follows from it. Nothing here suggests a legacy deployment target, and there is no separate branch for older systems in the documentation.

There is one more requirement that is easy to miss because it is a note rather than a list item. You also need to install the Maps SDK for iOS, which is also supported in Swift Package Manager at its own GitHub URL, so a Swift Package Manager setup means adding two packages rather than one.

Three installation routes and a version matrix

The library is installed alongside the Maps SDK, and the README gives a route for each of the three package managers in the iOS world.

The first step is always the same: include the GoogleMaps dependency using one of the available installation options, which are Swift Package Manager, CocoaPods, or manual. The second step is adding the utility library itself.

For Swift Package Manager, the package URL is the repository itself, and then you select the version of the utility library you want. For new projects the recommendation is to specify the latest version and use the up to next major option.

  https://github.com/googlemaps/google-maps-ios-utils

For CocoaPods, the Podfile carries both pods, and the utility pod is pinned to a specific version with a comment marking the release automation.

  use_frameworks!

  target 'TARGET_NAME' do
    pod 'GoogleMaps', '10.0.0'
    pod 'Google-Maps-iOS-Utils', '7.1.2' # x-release-please-version
  end

Then the install command, and you open the workspace that is created rather than the project.

  pod install

The Carthage route is the third, and it comes with a restriction stated in the summary of the section: it is only supported if you are using Maps SDK v7.1.2 or earlier. The Cartfile entry is a single line.

github "googlemaps/google-maps-ios-utils" ~> 7.1.2

The version matrix is the part to actually read, because it tells you which combination works. Version 6.x of this library supports the Maps SDK for iOS v9.x, version 5.0 supports v8.x, and version 4.2.2 supports v7.x. The library and the SDK move in generations, and picking the wrong pair is the most common integration problem here.

Importing, and what clustering looks like

The import statements differ by language, and both are one line.

import GoogleMapsUtils

@import GoogleMapsUtils;

The README also notes that you may need to import GoogleMaps as well, which is the SDK rather than the utility library.

The clustering example is the most useful piece of documentation in the file, because it shows the whole set of objects you assemble. You create a default cluster icon generator, a non-hierarchical distance based algorithm, and a default cluster renderer that takes the map view and the icon generator, and then you create the cluster manager with the map, the algorithm, and the renderer.

The code sets up the cluster manager from three objects you can vary. The icon generator, which decides what a cluster badge looks like, the algorithm, which decides which markers are grouped, and the renderer, which draws them. The distance based algorithm named here is the non-hierarchical one, which means clusters are formed from proximity rather than from a tree, and that choice matters for how clusters appear and disappear as you zoom.

The sample applications for both Swift and Objective-C are in the samples directory of the repository, and the documentation is available both on the developer site and in the docs directory.

KML, and the geometry renderer

The second worked example covers KML, and it is short enough to take in one reading.

You parse the file with the KML parser, which takes a URL, and then you hand the parsed placemarks, the styles, and the style maps to a geometry renderer that is bound to your map view, and then you tell it to render.

import GoogleMaps
import GoogleMapsUtils

func renderKml() {
    // Parse KML
    let path: String = // Path to your KML file...
    let kmlUrl = URL(fileURLWithPath: path)
    let kmlParser = GMUKmlParser(url: kmlUrl)
    kmlParser.parse()

    // Render parsed KML
    let renderer = GMUGeometryRenderer(
        map: mapView,
        geometries: kmlParser.placemarks,
        styles: kmlParser.styles,
        styleMaps: kmlParser.styleMaps
    )
    renderer.render()
}

Two details in that snippet are worth noting. The parser exposes three separate collections, the placemarks, the styles, and the style maps, and all three have to be passed to the renderer, so the KML styling travels with the geometry rather than being discarded. And the parser is fed a file URL, which means the KML is read locally rather than fetched, so an app that ships a bundle of placemarks does not need network access to draw them.

The same geometry renderer is what the GeoJSON support uses, which is why the two are described together as the geometry libraries in the feature list.

Terms of service, the EEA change, and how the releases work

The last section of the README is the one with the legal weight, and it has two parts.

The first is the general terms. This library uses Google Maps Platform services, and use of those services through the library is subject to the Google Maps Platform terms of service. That is worth reading as a practical constraint, because the library is a thin wrapper and the terms flow through it to your application.

The second is specific and dated. For developers whose billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA terms of service apply to your use. A date in the middle of a release cycle is the kind of thing that matters if you ship inside the EEA, because the obligations differ by where the billing address is rather than by where the user is.

The repository layout shows how the release process is run, and it is unusual for a Google library. Alongside the usual sources, tests, samples, and documentation, there is a podspec, a Package.swift with a resolved file, a podfile template, a privacy manifest, a test plan, and a release-please configuration with its manifest file. The release-please setup is what produces the version comment in the podspec and in the CocoaPods instructions, and the comment in the podfile says so directly, noting that the marker is used for release automation and can be omitted.

That combination, a CocoaPods pod, a Swift package, and an automated release pipeline, is what a library that has to support several installation routes and several SDK generations ends up looking like.

Editorial conclusion

google-maps-ios-utils fits an iOS team that already uses the Maps SDK and needs the parts of a mapping application that the SDK itself does not provide, such as clustering, heatmaps, and KML rendering, without writing them from scratch. It does not fit a project that only needs a map view, because it is a companion library rather than the SDK, and it does not fit a team that cannot obtain a Google Maps Platform API key. Verify first that the version of this library you pick matches the generation of the Maps SDK you are on, since the compatibility list is explicit, that your deployment target is iOS 16 or newer, and that you have read the terms of service change that applies to developers billing in the European Economic Area.

Frequently asked questions

Official sources

1. googlemaps/google-maps-ios-utils on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases