MarkerClusterer 2.0


I found very interesting the MarkerClusterer 1.0 made by Xiaoxi Wu. MarkerClusterer is a JavaScript class that allows programmers to group Google Maps markers into clusters. In other words, if your map has many markers to be displayed, it groups them in order to make the visualization better and the computation more efficient.


Nonetheless, I think the original 1.0 Version was rather limited in its way of giving information about the cluster: it only allowed to get the number of items in the cluster as the label of the cluster marker.

I augmented the original class in order to allow programmers:
– to associate a value with each marker (i.e. with each marked location)
– to provide the MarkerClusterer with a function that allows the label to be calculated on the fly; the function is calculated over the values attached to the items in the cluster considered.

Here you can see the previous version and my modified release


MarkerClusterer 2.0 is useful in those situations in which you want to display aggregate data on a certain area. Examples include:

– weather forecasts: you can display national and regional averages using clusters
– distribution of wealth: you can display the total amount of money in a map region, as well as the average
– hospital death rates: this is actually the data set from which I originally got the idea of improving MarkerClusterer. You can find more information here


If you know how to use the original MarkerClusterer 1.0, there won’t be such difference for you. Roughly, you need to pass the MarkerClusterer two more arguments:
– an array of values
– a function (here’s an example with a function for calculating the average).

Both of them can be defined in your javascript/html page. The creation of the MarkerClusterer will be as follows:
var markerCluster = new MarkerClusterer(map, markers, options, opt_values, opt_function);

  • map is a standard Google Map
  • markers is an Array of Google GMarker
  • options is an object of type MarkerClustererOptions
  • opt_values is an array of Numbers
  • opt_function is a function.

If opt_values or opt_function are null, the behaviour is that of the standard ClusterMarkerer 1.0.

For a more concrete example of use, let us suppose you want to show sums of population data in a map. All you have to do is:

0 – create map in the “usual” way (this is my favourite)
var map = new GMap2(document.getElementById("map_canvas"), { size: new GSize(800,600) } );
map.addControl(new GLargeMapControl());
map.setCenter(new GLatLng(53.4602,1.000), 5);
var mapControl = new GMapTypeControl();

1 – initialize array
var values = [];

2 – define a sum function
function avg(array) {
var total=0
for (var i=0;i<array.length; i++) total=total+parseFloat(array[i]);
return Math.round(total*100/array.length)/100;

3 – create a marker (in your favourite way, here I suppose to have a function to cater for that.
var point = new GLatLng(latitude, longitude);
var marker = new GMarker(point, markerOptions);
markers.push(marker); //this is the ClusterMarkerer-specific array

4 – add its relevant value in an array (in the same order, as both arrays are positional)

5 – create and add the MarkerClusterer
var mcOptions = { gridSize: 50, maxZoom: 15};
var markerCluster = new MarkerClusterer(map, markers, mcOptions, values, avg);


markerclusterer.js [24 KB]


I’m thinking about adding the possibility of treating the ClusterMarker as a normal marker, in order to attach infoboxes to it (for example, I could be interested in showing the list of markers in a cluster, upon clicking on its ClusterMarkerer).

7 replies on “MarkerClusterer 2.0”

How about the custom labels for the clusters? I need to plot populations on the map and need the population values to show as the label for the clusters?

Hi Erick,
sorry – I haven’t touched this library since it got added to the official distribution and it’s been heavily modified since.
I would recommend you join the mailing list and ask on there, I’m sure the current maintainer will be able to advise.

Hi Erick,

This is great, exactly what I was looking for… until I realised it wasn’t for v3.

Reading Giuseppe’s comments above I thought that your excellent fork must have been included in the new official distribution but I can’t find any references in the official one that allow me to display values rather than marker counts.

Your last comment suggests that you might have rebuilt your fork for v3. Is this correct? If so, are you able to share your new fork with us?

This is the way MarkerClusterer should be used!

Leave a Reply to Erick Cancel reply

Your email address will not be published. Required fields are marked *