1# supercluster [](https://github.com/mourner/projects) [](https://travis-ci.org/mapbox/supercluster) 2 3A very fast JavaScript library for geospatial point clustering for browsers and Node. 4 5```html 6<script src="https://unpkg.com/supercluster@4.1.1/dist/supercluster.min.js"></script> 7``` 8 9```js 10var index = supercluster({ 11 radius: 40, 12 maxZoom: 16 13}); 14index.load(points); 15index.getClusters([-180, -85, 180, 85], 2); 16``` 17 18Clustering 6 million points in Leaflet: 19 20 21 22## Install 23 24Install using NPM (`npm install supercluster`) or Yarn (`yarn add supercluster`), then: 25 26```js 27// import as a ES module 28import supercluster from 'supercluster'; 29 30// or require in Node / Browserify 31const supercluster = require('supercluster'); 32``` 33 34Or use a browser build directly: 35 36```html 37<script src="https://unpkg.com/supercluster@4.1.1/dist/supercluster.min.js"></script> 38``` 39 40## Methods 41 42#### `load(points)` 43 44Loads an array of [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) objects. Each feature's `geometry` must be a [GeoJSON Point](https://tools.ietf.org/html/rfc7946#section-3.1.2). Once loaded, index is immutable. 45 46#### `getClusters(bbox, zoom)` 47 48For the given `bbox` array (`[westLng, southLat, eastLng, northLat]`) and integer `zoom`, returns an array of clusters and points as [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) objects. 49 50#### `getTile(z, x, y)` 51 52For a given zoom and x/y coordinates, returns a [geojson-vt](https://github.com/mapbox/geojson-vt)-compatible JSON tile object with cluster/point features. 53 54#### `getChildren(clusterId)` 55 56Returns the children of a cluster (on the next zoom level) given its id (`cluster_id` value from feature properties). 57 58#### `getLeaves(clusterId, limit = 10, offset = 0)` 59 60Returns all the points of a cluster (given its `cluster_id`), with pagination support: 61`limit` is the number of points to return (set to `Infinity` for all points), 62and `offset` is the amount of points to skip (for pagination). 63 64#### `getClusterExpansionZoom(clusterId)` 65 66Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature) given the cluster's `cluster_id`. 67 68## Options 69 70| Option | Default | Description | 71|----------|---------|-------------------------------------------------------------------| 72| minZoom | 0 | Minimum zoom level at which clusters are generated. | 73| maxZoom | 16 | Maximum zoom level at which clusters are generated. | 74| radius | 40 | Cluster radius, in pixels. | 75| extent | 512 | (Tiles) Tile extent. Radius is calculated relative to this value. | 76| nodeSize | 64 | Size of the KD-tree leaf node. Affects performance. | 77| log | false | Whether timing info should be logged. | 78 79### Property map/reduce options 80 81In addition to the options above, supercluster supports property aggregation with the following three options: 82 83- `initial`: a function that returns an object with cluster's initial properties. 84- `map`: a function that returns properties to use for individual points. 85- `reduce`: a reduce function for calculating properties in clusters. 86 87Example of setting up a `sum` cluster property that accumulates the sum of `myValue` property values: 88 89```js 90var index = supercluster({ 91 initial: function() { return {sum: 0}; }, 92 map: function(props) { return {sum: props.myValue}; }, 93 reduce: function(accumulated, props) { accumulated.sum += props.sum; } 94}); 95``` 96 97## Developing Supercluster 98 99``` 100npm install # install dependencies 101npm run build # generate dist/supercluster.js and dist/supercluster.min.js 102npm test # run tests 103``` 104
){kind=link}
){kind=link}
){kind=link}