Overview

A Google Maps JavaScript API v3 library to create and manage per-zoom-level clusters for large amounts of markers.

Examples

Simple Example

<div id="map-container"><div id="map"></div></div>
<script src="markerclusterer.js"></script>
<script>
    function initialize() {
        var center = new google.maps.LatLng(51.5074, 0.1278);

        var map = new google.maps.Map(document.getElementById('map'), {
          zoom: 3,
          center: center,
          mapTypeId: google.maps.MapTypeId.ROADMAP
        });

        var markers = [];
        var marker = new google.maps.Marker({
            position: new google.maps.LatLng(51.5074, 0.1278)
        });
        markers.push(marker);

        var options = {
            imagePath: 'images/m'
        };

        var markerCluster = new MarkerClusterer(map, markers, options);
    }

    google.maps.event.addDomListener(window, 'load', initialize);
</script>
Show Example

Advanced Example

With this example, you can test MarkerClusterer with different max zoom levels, grid size and styles, all the options.

Show Example

Speed Test

This example will compare adding markers with MarkerClusterer to the normal method of adding markers, and display the time for each.

Show Example

Reference

The class MarkerClusterer extends google.maps.OverlayView

Constructor

Constructor Description
MarkerClusterer(map:google.maps.Map, opt_markers:Array.<google.maps.Marker>, opt_options:Object) A Marker Clusterer that clusters markers.

Options

Name Type Description
gridSize number The grid size of a cluster in pixels.
maxZoom number The maximum zoom level that a marker can be part of a cluster.
zoomOnClick boolean Whether the default behaviour of clicking on a cluster is to zoom into it.
averageCenter boolean Whether the center of each cluster should be the average of all markers in the cluster.
minimumClusterSize number The minimum number of markers to be in a cluster before the markers are hidden and a count is shown.
ignoreHiddenMarkers boolean Whether to ignore markers that are not visible or count and cluster them anyway.
cssClass string One or more CSS class for styling this marker.
styles Array An array of objects that have style properties.
onMouseoverCluster Function(clusterIcon: ClusterIcon, event: MouseEvent) The event handler used for onmouseover on a cluster, first argument is the ClusterIcon.
onMouseoutCluster Function(clusterIcon: ClusterIcon, event: MouseEvent) The event handler used for onmouseout on a cluster, first argument is the ClusterIcon.
drawCluster Function Custom draw method for ClusterIcon.
hideCluster Function Custom hide method for ClusterIcon.
showCluster Function Custom hide method for ClusterIcon.
onAddCluster Function Custom onAdd method for ClusterIcon.
onRemoveCluster Function Custom onRemove method for ClusterIcon.

Styles

Name Type Description
url string The image url.
height number The image height.
width number The image width.
anchor Array The anchor position of the label text.
textColor string The text color.
textSize number The text size.
backgroundPosition string The position of the backgound x, y.
iconAnchor Array The anchor position of the icon x, y.

Methods

Methods Return Value Description
addMarker(marker:google.maps.Marker, opt_nodraw:boolean) None Adds a marker to the clusterer and redraws if needed.
addMarkers(markers:Array.<google.maps.Marker>, opt_nodraw:boolean) None Adds an array of markers to the clusterer.
clearMarkers() None Clears all clusters and markers from the clusterer.
getCalculator() function(Array|number) Gets the calculator function.
getExtendedBounds(bounds:google.maps.LatLngBounds) google.maps.LatLngBounds Extends a bounds object by the grid size.
getGridSize() number Gets the size of the grid.
getMap() google.maps.Map Gets the google map that the clusterer is associated with.
getMarkers() Array. Gets the array of markers in the clusterer.
getMaxZoom() number Gets the max zoom for the clusterer.
getStyles() Object Gets the styles.
getTotalClusters() number Gets the number of clusters in the clusterer.
getTotalMarkers() number Gets the number of markers in the clusterer.
isZoomOnClick() boolean Whether zoom on click is set.
redraw() None Redraws the clusters.
removeMarker(marker:google.maps.Marker) boolean Removes a marker from the cluster.
repaint() None Forces a refresh of clusters (by calling resetViewport and redraw) while avoiding flickering. Useful for moving markers.
resetViewport() None Clears all existing clusters and recreates them.
setCalculator(calculator:function(Array|number)) None Sets the calculator function.
setGridSize(size:number) None Sets the size of the grid.
setMap(map:google.maps.Map) None Sets the google map that the clusterer is associated with.
setMaxZoom(maxZoom:number) None Sets the max zoom for the clusterer.
setStyles(styles:Object) None Sets the styles.
getMarkersCluster(marker:google.maps.Marker) Cluster Returns the marker clusterer that the cluster is associated with.