Marker Clustering

This page describes the marker clustering utility that's available in the utility library for the Maps SDK for iOS.

By clustering your markers, you can put a large number of markers on a map without making the map hard to read. The marker clustering utility helps you manage multiple markers at different zoom levels.

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.

Quick start

Run pod try Google-Maps-iOS-Utils to use the demo app shipped with the utility library. The demo app provides a sample implementation of the marker clustering utility.

For the full code sample, see the ObjCDemoApp and SwiftDemoApp on GitHub.

The following screenshot shows the default style of marker clusters:

Below is an example of custom marker clusters:

Prerequisites and notes

The marker clustering utility is part of the Maps SDK for iOS Utility Library. If you haven't yet set up the library, follow the setup guide before reading the rest of this page.

For best performance, the recommended maximum number of markers is 10,000.

Add a simple marker clusterer

To represent the markers you want to display on the map, implement the GMUClusterItem protocol in your ViewController. The following code defines a point of interest, the POIItem class, representing the markers to be managed in clusters on the map:

Swift

/// Point of Interest Item which implements the GMUClusterItem protocol.
class POIItem: NSObject, GMUClusterItem {
  var position: CLLocationCoordinate2D
  var name: String!

  init(position: CLLocationCoordinate2D, name: String) {
    self.position = position
    self.name = name
  }
}

Objective-C

#import "ViewController.h"

#import <Google-Maps-iOS-Utils/GMUMarkerClustering.h>
#import <GoogleMaps/GoogleMaps.h>

// Point of Interest Item which implements the GMUClusterItem protocol.
@interface POIItem : NSObject<GMUClusterItem>

@property(nonatomic, readonly) CLLocationCoordinate2D position;
@property(nonatomic, readonly) NSString *name;

- (instancetype)initWithPosition:(CLLocationCoordinate2D)position name:(NSString *)name;

@end

To use the cluster manager, instantiate a GMUClusterManager object and pass it a GMSMapView, a GMUClusterAlgorithm, and a GMUClusterRenderer. The library includes default implementations of the cluster algorithm and renderer. The following code creates a cluster manager using the GMUNonHierarchicalDistanceBasedAlgorithm and the GMUDefaultClusterRenderer that are included in the utility library:

Swift

class ViewController: UIViewController, GMUClusterManagerDelegate,
    GMSMapViewDelegate {

  private var mapView: GMSMapView!
  private var clusterManager: GMUClusterManager!

  override func viewDidLoad() {
    super.viewDidLoad()

    // Set up the cluster manager with the supplied icon generator and
    // renderer.
    let iconGenerator = GMUDefaultClusterIconGenerator()
    let algorithm = GMUNonHierarchicalDistanceBasedAlgorithm()
    let renderer = GMUDefaultClusterRenderer(mapView: mapView,
                                clusterIconGenerator: iconGenerator)
    clusterManager = GMUClusterManager(map: mapView, algorithm: algorithm,
                                                      renderer: renderer)

    // Generate and add random items to the cluster manager.
    generateClusterItems()

    // Call cluster() after items have been added to perform the clustering
    // and rendering on map.
    clusterManager.cluster()
  }
}

Objective-C

@implementation ViewController {
  GMSMapView *_mapView;
  GMUClusterManager *_clusterManager;
}

- (void)loadView {
  GMSCameraPosition *camera =
      [GMSCameraPosition cameraWithLatitude:kCameraLatitude longitude:kCameraLongitude zoom:10];
  _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
  self.view = _mapView;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // Set up the cluster manager with a supplied icon generator and renderer.
  id<GMUClusterAlgorithm> algorithm =
      [[GMUNonHierarchicalDistanceBasedAlgorithm alloc] init];
  id<GMUClusterIconGenerator> iconGenerator =
      [[GMUDefaultClusterIconGenerator alloc] init];
  id<GMUClusterRenderer> renderer =
      [[GMUDefaultClusterRenderer alloc] initWithMapView:_mapView
                                    clusterIconGenerator:iconGenerator];
  _clusterManager =
      [[GMUClusterManager alloc] initWithMap:_mapView
                                   algorithm:algorithm
                                    renderer:renderer];

  // Generate and add random items to the cluster manager.
  [self generateClusterItems];

  // Call cluster() after items have been added
  // to perform the clustering and rendering on map.
  [_clusterManager cluster];
}

Feed your markers into the cluster as GMUClusterItem objects by calling clusterManager:addItem:. The following code randomly generates cluster items (POIs) within the scope of the map's camera, then feeds them to the cluster manager:

Swift

/// Randomly generates cluster items within some extent of the camera and
/// adds them to the cluster manager.
private func generateClusterItems() {
  let extent = 0.2
  for index in 1...kClusterItemCount {
    let lat = kCameraLatitude + extent * randomScale()
    let lng = kCameraLongitude + extent * randomScale()
    let name = "Item \(index)"
    let item =
        POIItem(position: CLLocationCoordinate2DMake(lat, lng), name: name)
    clusterManager.addItem(item)
  }
}

/// Returns a random value between -1.0 and 1.0.
private func randomScale() -> Double {
  return Double(arc4random()) / Double(UINT32_MAX) * 2.0 - 1.0
}

Objective-C

// Randomly generates cluster items within some extent of the camera and
// adds them to the cluster manager.
- (void)generateClusterItems {
  const double extent = 0.2;
  for (int index = 1; index <= kClusterItemCount; ++index) {
    double lat = kCameraLatitude + extent * [self randomScale];
    double lng = kCameraLongitude + extent * [self randomScale];
    NSString *name = [NSString stringWithFormat:@"Item %d", index];
    id<GMUClusterItem> item =
        [[POIItem alloc] initWithPosition:CLLocationCoordinate2DMake(lat, lng)
                                     name:name];
    [_clusterManager addItem:item];
  }
}

// Returns a random value between -1.0 and 1.0.
- (double)randomScale {
  return (double)arc4random() / UINT32_MAX * 2.0 - 1.0;
}

Handle events on markers and clusters

Using the map delegate: In general when using the Maps SDK for iOS, to listen to events on the map you must implement the GMSMapViewDelegate protocol. By default when using a GMUClusterManager, your map delegate works as usual. You can listen to map events, but you can't listen to the type-safe cluster manager events. When the user taps a marker, an individual cluster item, or a cluster, the API triggers mapView:didTapMarker: and attaches the extra cluster data to the marker.userData property. You can use conformsToProtocol to check what the user tapped.

Using the cluster manager delegate: If you want to listen to the type-safe events on the cluster manager, you must implement the GMUClusterManagerDelegate as well as the GMSMapViewDelegate. Typically, you implement both these protocols in the view controller that displays the map. Then call clusterManager.setDelegate:mapDelegate: to set the cluster manager delegate as well as the map delegate, as shown in this code sample:

Swift

class ViewController: UIViewController, GMUClusterManagerDelegate, GMSMapViewDelegate {

  private var mapView: GMSMapView!
  private var clusterManager: GMUClusterManager!

  override func viewDidLoad() {
    super.viewDidLoad()

    // ... Rest of code omitted for easy reading.

    // Register self to listen to both GMUClusterManagerDelegate and
    // GMSMapViewDelegate events.
    clusterManager.setDelegate(self, mapDelegate: self)
  }

  // MARK: - GMUClusterManagerDelegate

  func clusterManager(clusterManager: GMUClusterManager, didTapCluster cluster: GMUCluster) {
    let newCamera = GMSCameraPosition.cameraWithTarget(cluster.position,
      zoom: mapView.camera.zoom + 1)
    let update = GMSCameraUpdate.setCamera(newCamera)
    mapView.moveCamera(update)
  }

  // MARK: - GMUMapViewDelegate

  func mapView(mapView: GMSMapView, didTapMarker marker: GMSMarker) -> Bool {
    if let poiItem = marker.userData as? POIItem {
      NSLog("Did tap marker for cluster item \(poiItem.name)")
    } else {
      NSLog("Did tap a normal marker")
    }
    return false
  }
}

Objective-C

@interface ViewController ()<GMUClusterManagerDelegate, GMSMapViewDelegate>
@end

@implementation ViewController {
  GMSMapView *_mapView;
  GMUClusterManager *_clusterManager;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // ... Rest of code omitted for easy reading.

  // Register self to listen to both GMUClusterManagerDelegate and
  // GMSMapViewDelegate events.
  [_clusterManager setDelegate:self mapDelegate:self];
}

#pragma mark GMUClusterManagerDelegate

- (void)clusterManager:(GMUClusterManager *)clusterManager didTapCluster:(id<GMUCluster>)cluster {
  GMSCameraPosition *newCamera =
      [GMSCameraPosition cameraWithTarget:cluster.position zoom:_mapView.camera.zoom + 1];
  GMSCameraUpdate *update = [GMSCameraUpdate setCamera:newCamera];
  [_mapView moveCamera:update];
}

#pragma mark GMSMapViewDelegate

- (BOOL)mapView:(GMSMapView *)mapView didTapMarker:(GMSMarker *)marker {
  POIItem *poiItem = marker.userData;
  if (poiItem != nil) {
    NSLog(@"Did tap marker for cluster item %@", poiItem.name);
  } else {
    NSLog(@"Did tap a normal marker");
  }
  return NO;
}

The cluster manager now intercepts any events that you've implemented on clusterManager. It forwards any remaining events to the map delegate, if provided. Note that events for standard markers (that is, markers not generated by the cluster renderer) are always forwarded to the map delegate.

You can listen for the following events when using the GMUClusterManagerDelegate:

• clusterManager:didTapCluster: is called when the user taps a cluster of markers.
• clusterManager:didTapClusterItem: is called when the user taps an individual cluster item (marker).

Customize the marker clusters

You can provide a custom implementation for the GMUClusterRenderer, GMUClusterIconGenerator, or GMUClusterAlgorithm. You can base your custom implementation on the sample implementation of these protocols included in the utility library, or you can code a fully custom implementation by fulfilling the protocols.