AI-generated Key Takeaways

outlined_flag

• The marker clustering utility for the Maps SDK for iOS helps manage the display of large numbers of markers by grouping them into clusters at different zoom levels.

• Implementing marker clustering involves creating a cluster manager, adding markers to it, and invoking the clustering process.

• You can customize the appearance and behavior of marker clusters by providing your own implementations for cluster rendering, icon generation, and clustering algorithms.

• The utility library includes default implementations for cluster rendering, icon generation, and clustering algorithms that you can use directly or as a basis for customization.

• To handle events on markers and clusters, implement theGMSMapViewDelegate protocol and check themarker.userData property to determine if a cluster or individual marker was tapped.

This page describes the marker clustering utility that's available in theutility 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.

The following screenshot shows the default style of marker clusters:

Below is an example of custom marker clusters:

Prerequisites and notes

Maps SDK for iOS Utility Library

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

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

Location permission

This example uses the device's GPS to locate the user and the map on their coordinates. To enable this, you must add a description to theNSLocationWhenInUseUsageDescription permission in the project'sInfo.plist file.

To add this, do the following:

1. Click theInfo.plist file in the Project Navigator in Xcode to open the Property List Editor.
2. Click the '+' icon next to 'Information Property List' to add a new property.
3. In the 'key' field, type 'NSLocationWhenInUseUsageDescription'. Xcode will automatically translate this to the long name 'Privacy - Location When In Use Usage Description'. For a complete list of possible location permission properties, see Requesting Authorization for Location Services in the Apple Developer documentation.
4. Leave the 'Type' field set to 'String'.
5. In the 'Value' field, type a description of the reason your app requires the use of the user's location. For example, "Locates the user to provide nearby business listings."

Implementing marker clustering

Implementing marker clustering takes three steps:

1. Create a cluster manager instance.
2. Pass the markers you want to cluster to the cluster manger.
3. Invoke the cluster manager.

Creating the cluster manager

To use the cluster manager, do the following:

1. Set theViewController where your map is rendered to conform to theGMSMapViewDelegate protocol.
2. Create an instance ofGMUClusterManager.
3. Pass the the instance ofGMSMapView you want to implement marker clustering in and implementations of the following protocols to theGMUClusterManager instance:
   • GMUClusterIconGenerator: Provides application logic that fetches the cluster icons to be used at different zoom levels.
   • GMUClusterAlgorithm: Specifies an algorithm that determines the behavior of how markers are clustered, such as the distance between markers to include in the same cluster.
   • GMUClusterRenderer: Provides application logic that handles the actual rendering of the cluster icons on the map.
4. Set the map delegate on theGMUClusterManager instance.

The utility library includes default implementations of the icon generator (GMUDefaultClusterIconGenerator), algorithm (GMUNonHierarchicalDistanceBasedAlgorithm) and renderer (GMUDefaultClusterRenderer). You may optionally create your own custom clustrering icon genertator, algorithm and renderer.

The following code creates a cluster manager using these defaults in theviewDidLoad callback ofViewController:

importGoogleMapsimportGoogleMapsUtilsclassMarkerClustering:UIViewController,GMSMapViewDelegate{privatevarmapView:GMSMapView!privatevarclusterManager:GMUClusterManager!overridefuncviewDidLoad(){super.viewDidLoad()// Set up the cluster manager with the supplied icon generator and// renderer.leticonGenerator=GMUDefaultClusterIconGenerator()letalgorithm=GMUNonHierarchicalDistanceBasedAlgorithm()letrenderer=GMUDefaultClusterRenderer(mapView:mapView,clusterIconGenerator:iconGenerator)clusterManager=GMUClusterManager(map:mapView,algorithm:algorithm,renderer:renderer)// Register self to listen to GMSMapViewDelegate events.clusterManager.setMapDelegate(self)// ...}// ...}

@importGoogleMaps;@importGoogleMapsUtils;@interfaceMarkerClustering()<GMSMapViewDelegate>@end@implementationMarkerClustering{GMSMapView*_mapView;GMUClusterManager*_clusterManager;}-(void)viewDidLoad{[superviewDidLoad];// Set up the cluster manager with a supplied icon generator and renderer.id<GMUClusterAlgorithm>algorithm=[[GMUNonHierarchicalDistanceBasedAlgorithmalloc]init];id<GMUClusterIconGenerator>iconGenerator=[[GMUDefaultClusterIconGeneratoralloc]init];id<GMUClusterRenderer>renderer=[[GMUDefaultClusterRendereralloc]initWithMapView:_mapViewclusterIconGenerator:iconGenerator];_clusterManager=[[GMUClusterManageralloc]initWithMap:_mapViewalgorithm:algorithmrenderer:renderer];// Register self to listen to GMSMapViewDelegate events.[_clusterManagersetMapDelegate:self];// ...}// ...@end

Adding markers

There are two ways to add markers to the marker clusterer: individually or as an array.

Individual marker

letposition=CLLocationCoordinate2D(latitude:47.60,longitude:-122.33)letmarker=GMSMarker(position:position)clusterManager.add(marker)

CLLocationCoordinate2Dposition=CLLocationCoordinate2DMake(47.60,-122.33);GMSMarker*marker=[GMSMarkermarkerWithPosition:position];[_clusterManageraddItem:marker];

Array of markers

letposition1=CLLocationCoordinate2D(latitude:47.60,longitude:-122.33)letmarker1=GMSMarker(position:position1)letposition2=CLLocationCoordinate2D(latitude:47.60,longitude:-122.46)letmarker2=GMSMarker(position:position2)letposition3=CLLocationCoordinate2D(latitude:47.30,longitude:-122.46)letmarker3=GMSMarker(position:position3)letposition4=CLLocationCoordinate2D(latitude:47.20,longitude:-122.23)letmarker4=GMSMarker(position:position4)letmarkerArray=[marker1,marker2,marker3,marker4]clusterManager.add(markerArray)

CLLocationCoordinate2Dposition1=CLLocationCoordinate2DMake(47.60,-122.33);GMSMarker*marker1=[GMSMarkermarkerWithPosition:position1];CLLocationCoordinate2Dposition2=CLLocationCoordinate2DMake(47.60,-122.46);GMSMarker*marker2=[GMSMarkermarkerWithPosition:position2];CLLocationCoordinate2Dposition3=CLLocationCoordinate2DMake(47.30,-122.46);GMSMarker*marker3=[GMSMarkermarkerWithPosition:position3];CLLocationCoordinate2Dposition4=CLLocationCoordinate2DMake(47.20,-122.23);GMSMarker*marker4=[GMSMarkermarkerWithPosition:position4];NSArray<GMSMarker*>*markerArray=@[marker1,marker2,marker3,marker4];[_clusterManageraddItems:markerArray];

Invoking the marker clusterer

Once you have created your marker clusterer and passed it the markers you wish to cluster, all you have to do is call thecluster method on your marker clusterer instance.

clusterManager.cluster()

[_clusterManagercluster];

Handle events on markers and clusters

In general when using the Maps SDK for iOS, to listen to events on the map you must implement theGMSMapViewDelegate protocol. You can listen tomap 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 triggersmapView:didTapMarker: and attaches the extra cluster data to themarker.userData property. You can then check if theuserData conforms to theGMUCluster protocol to determine if a cluster icon or a marker was tapped.

funcmapView(_mapView:GMSMapView,didTapmarker:GMSMarker)->Bool{// center the map on tapped markermapView.animate(toLocation:marker.position)// check if a cluster icon was tappedifmarker.userDataisGMUCluster{// zoom in on tapped clustermapView.animate(toZoom:mapView.camera.zoom+1)NSLog("Did tap cluster")returntrue}NSLog("Did tap a normal marker")returnfalse}

-(BOOL)mapView:(GMSMapView*)mapViewdidTapMarker:(GMSMarker*)marker{// center the map on tapped marker[_mapViewanimateToLocation:marker.position];// check if a cluster icon was tappedif([marker.userDataconformsToProtocol:@protocol(GMUCluster)]){// zoom in on tapped cluster[_mapViewanimateToZoom:_mapView.camera.zoom+1];NSLog(@"Did tap cluster");returnYES;}NSLog(@"Did tap marker in cluster");returnNO;}

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

Customize marker clustering

You can provide a custom implementation for theGMUClusterRenderer,GMUClusterIconGenerator, orGMUClusterAlgorithm. 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.