Google Maps Android API v2

Google Maps Android Marker Clustering Utility

By clustering your markers, you can put a large number of markers on a map without making the map hard to read.

  1. Introduction
  2. Add a simple marker clusterer
  3. Customize the marker clusters

Introduction

The marker clustering utility helps you manage multiple markers at different zoom levels. To be precise, the 'markers' are actually 'items' at this point, and only become 'Markers' when they're rendered. But for the sake of clarity, this document will name them 'markers' throughout.

When a user views the map at a high zoom level, the individual markers show on the map. When the user zooms out, the markers gather together into clusters, to make viewing the map easier. The marker clustering utility is part of the Google Maps Android API Utility Library. If you haven't yet set up the library, follow the setup guide before reading the rest of this page.

A map with clustered markers
Clustered markers

To use the marker clustering utility, you will need to add markers as ClusterItem objects to the ClusterManager. The ClusterManager passes the markers to the Algorithm, which transforms them into a set of clusters. The ClusterRenderer takes care of the rendering, by adding and removing clusters and individual markers. The ClusterRenderer and Algorithm are pluggable and can be customized.

The utility library ships with a demo app providing sample implementations of the marker clustering utility. For help with running the demo app, see the setup guide. The demo app includes the following marker clustering samples:

  • ClusteringDemoActivity: A simple activity demonstrating marker clustering.
  • BigClusteringDemoActivity: Clustering with 2 000 markers.
  • CustomMarkerClusteringDemoActivity: Creating a custom design for clustered markers.

Add a simple marker clusterer

Follow the steps below to create a simple cluster of ten markers. The result will look like this, although the number of markers shown/clustered will change depending on the zoom level:

A map with ten clustered markers
Ten clustered markers

Here is a summary of the steps required:

  1. Implement ClusterItem to represent a marker on the map. The cluster item returns the position of the marker as a LatLng object.
  2. Add a new ClusterManager to group the cluster items (markers) based on zoom level.
  3. Set the map's OnCameraChangeListener() to the ClusterManager, since ClusterManager implements the listener.
  4. If you want to add specific functionality in response to a marker click event, set the map's OnMarkerClickListener() to the ClusterManager, since ClusterManager implements the listener.
  5. Feed the markers into the ClusterManager.

Looking at the steps in more detail: To create our simple cluster of ten markers, first create a MyItem class that implements ClusterItem.

public class MyItem implements ClusterItem {
    private final LatLng mPosition;

    public MyItem(double lat, double lng) {
        mPosition = new LatLng(lat, lng);
    }

    @Override
    public LatLng getPosition() {
        return mPosition;
    }
}

In your map activity, add the ClusterManager and feed it the cluster items. Note the type argument <MyItem>, which declares the ClusterManager to be of type MyItem.

private void setUpClusterer() {
    // Declare a variable for the cluster manager.
    private ClusterManager<MyItem> mClusterManager;

    // Position the map.
    getMap().moveCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(51.503186, -0.126446), 10));

    // Initialize the manager with the context and the map.
    // (Activity extends context, so we can pass 'this' in the constructor.)
    mClusterManager = new ClusterManager<MyItem>(this, getMap());

    // Point the map's listeners at the listeners implemented by the cluster
    // manager.
    getMap().setOnCameraChangeListener(mClusterManager);
    getMap().setOnMarkerClickListener(mClusterManager);

    // Add cluster items (markers) to the cluster manager.
    addItems();
}

private void addItems() {

    // Set some lat/lng coordinates to start with.
    double lat = 51.5145160;
    double lng = -0.1270060;

    // Add ten cluster items in close proximity, for purposes of this example.
    for (int i = 0; i < 10; i++) {
        double offset = i / 60d;
        lat = lat + offset;
        lng = lng + offset;
        MyItem offsetItem = new MyItem(lat, lng);
        mClusterManager.addItem(offsetItem);
    }
}

Customize the marker clusters

The ClusterManager constructor creates a DefaultClusterRenderer and a NonHierarchicalDistanceBasedAlgorithm. You can change the ClusterRenderer and the Algorithm using the setAlgorithm(Algorithm<T> algorithm) and setRenderer(ClusterRenderer<T> view) methods of ClusterManager.

You can implement ClusterRenderer to customize the rendering of the clusters. DefaultClusterRenderer provides a good base to start from. By subclassing DefaultClusterRenderer, you can override the defaults.

For an in-depth example of customization, take a look at CustomMarkerClusteringDemoActivity in the demo app that ships with the utility library.

A map with custom clustered markers
Custom clustered markers

The CustomMarkerClusteringDemoActivity defines its own cluster item, a Person, and renders it by extending the DefaultClusterRenderer as PersonRenderer.

The demo also shows how to implement the ClusterManager.OnClusterClickListener<Person> interface to display more information about the person when the cluster is clicked. You can also implement ClusterManager.OnClusterItemClickListener<Person> in a similar way.

For help with running the demo app, see the setup guide.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.