MarkerClusterer

This javascript library creates and manages per-zoom-level clusters for large amounts of markers (hundreds or thousands). This library was inspired by the Maptimize hosted clustering solution.

How it works:
The MarkerClusterer will group markers into clusters according to their distance from a cluster's center. When a marker is added, the marker cluster will find a position in all the clusters, and if it fails to find one, it will create a new cluster with the marker. The number of markers in a cluster will be displayed on the cluster marker. When the map viewport changes, MarkerClusterer will destroy the clusters in the viewport and regroup them into new clusters.

For a description and examples of how to use this library, check out the how-to.

class MarkerClusterer

Constructor

Constructor Description
MarkerClusterer(map:GMap2, opt_markers:Array of GMarker, opt_opts:MarkerClustererOptions) Creates a new MarkerClusterer to cluster markers on the map.

Methods

Methods Return Value Description
addMarkers(markers:Array of GMarker) None Add a set of markers.
clearMarkers() None Remove all markers from MarkerClusterer.
getCalculator() Object Get calculator function.
getParentCluster(marker:GMarker) Cluster Returns the cluster containing this marker, if any.
getStyles() Array of String Get cluster marker images of this marker cluster. Mostly used by Cluster
getTotalClusters() int Get total number of clusters.
getTotalMarkers() Number Get total number of markers.
isZoomOnClick() Boolean Get boolean value representing whether default behaviour of zooming on cluster upon clicking should be used.
removeMarker(marker:GMarker) None Remove a marker.
resetViewport() None Collect all markers of clusters in viewport and regroup them.
setCalculator(calculator:Function) None Set calculator function

class MarkerClustererOptions

This class represents optional arguments to the MarkerClusterer constructor. There is no constructor for this class. Instead, this class is instantiated as a javascript object literal.

Properties

Properties Type Description
calculator Function A function to calculator what will be showed on cluster marker and what kind of style will cluster marker be. This function auto called by Cluster. The default calculator will show number of markers in a cluster. This function take one parm: markers. You can add some property to marker of this markers array to calculat values. This function returns an object: { 'text': 'The text to be showed on cluster marker', 'index': 'Style index in array of MarginStylesOptions user passed.' }
gridSize Number The grid size of a cluster in pixel. Each cluster will be a square. If you want the algorithm to run faster, you can set this value larger. The default value is 60.
maxZoom Number The max zoom level monitored by a marker cluster. If not given, the marker cluster assumes the maximum map zoom level. When maxZoom is reached or exceeded all markers will be shown without cluster.
styles Array of MarkerStyleOptions Custom styles for the cluster markers. The array should be ordered according to increasing cluster size, with the style for the smallest clusters first, and the style for the largest clusters last.
zoomOnClick Boolean Whether default behaviour of zooming on a cluster upon clicking should be used. The default value is true.

class MarkerStyleOptions

An array of these is passed into the MarkerClustererOptions styles option. There is no constructor for this class. Instead, this class is instantiated as a javascript object literal.

Properties

Properties Type Description
height Number Image height.
height Number Image width.
opt_anchor Array of Number Anchor for label text, like [24, 12]. If not set, the text will align center and middle.
opt_textColor String Text color. The default value is "black".
opt_textSize Number Text size in px. The default value is 11.
url String Image url.