Javascript marker clustering for Google Maps



Everyone who works with large data sets in Google Maps has come across the problem of displaying a bunch of markers in a small area. Not just an eyesore, displaying anything more than a hundred marker icons at a time can bog the browser down on a lot of platforms, Safari on PPC Macs delivering the most pain.

The solution is to cluster nearby markers into an aggregate marker when there are too many markers being displayed, or when markers are so close at a particular zoom level that they completely overlap. For extremely large datasets this is most efficiently done on the back-end, with successive AJAX calls refreshing the marker set from a PHP script that filters out the visible markers from the set.

You can also handle the clustering on the client side, using javascript to scan the entire set of locations and dynamically determine what’s visible and what should be clustered. The downside is that you have to download the entire set and store it in the browser’s memory, but unless you start getting well into tens of thousands of markers this isn’t a big deal. The benefit to the client side method is that it’s less complex, it lets you work around large result sets from back-end APIs that you can’t control, and with ACME Labs’ Clusterer javascript library it’s extremely easy to code.

To use Clusterer, first download and include the Clusterer2.js file from the link below in your maps page. Then you need to instantiate a Clusterer object, passing your map object to its constructor:

var clusterManager = new Clusterer(map);

From there, you use it in place of the traditional MarkerManager or any addOverlay calls by calling the Clusterer’s addMarker method. It takes two parameters, the marker to add, and a text string that will be listed in the cluster’s contents when it is clicked:

clusterManager.AddMarker(marker, "Marker Description");

The cluster manager will take care of all the dirty work, only displaying items when they are within your view, and dynamically clustering them appropriately when there are too many on the screen at once. When one of the clusters is clicked, it will display a list of the locations inside of it. Most of what you’d want to tweak, like the threshold at which to start clustering and the icon used for representing a cluster, are all adjustable through the API via some self-explanatory methods such as SetMaxVisibleMarkers(n) and SetIcon(icon). Follow the link below for more information, or read the source for a few of the less-documented options.

Clusterer documentation
Clusterer source

Discuss this article with the rest of the community on our Discord server!