{"id":13426295,"url":"https://github.com/mapbox/supercluster","last_synced_at":"2025-05-13T19:11:04.022Z","repository":{"id":41203182,"uuid":"47860620","full_name":"mapbox/supercluster","owner":"mapbox","description":"A very fast geospatial point clustering library for browsers and Node.","archived":false,"fork":false,"pushed_at":"2024-08-15T05:07:57.000Z","size":337,"stargazers_count":2183,"open_issues_count":38,"forks_count":300,"subscribers_count":147,"default_branch":"main","last_synced_at":"2025-04-27T04:59:33.069Z","etag":null,"topics":["algorithm","clustering","computational-geometry","javascript","maps"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-12T02:13:07.000Z","updated_at":"2025-04-26T20:47:16.000Z","dependencies_parsed_at":"2022-07-14T10:31:21.421Z","dependency_job_id":"25f6e81d-6721-42c7-8998-b465f66e4411","html_url":"https://github.com/mapbox/supercluster","commit_stats":{"total_commits":161,"total_committers":22,"mean_commits":7.318181818181818,"dds":"0.17391304347826086","last_synced_commit":"fff7326c0232c3d488afee93c93c6b8eac5bcb46"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fsupercluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fsupercluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fsupercluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fsupercluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapbox","download_url":"https://codeload.github.com/mapbox/supercluster/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251089620,"owners_count":21534523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","clustering","computational-geometry","javascript","maps"],"created_at":"2024-07-31T00:01:31.189Z","updated_at":"2025-04-27T05:00:06.748Z","avatar_url":"https://github.com/mapbox.png","language":"JavaScript","readme":"# supercluster [![Simply Awesome](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects) [![Node](https://github.com/mapbox/supercluster/actions/workflows/node.yml/badge.svg)](https://github.com/mapbox/supercluster/actions/workflows/node.yml)\n\nA very fast JavaScript library for geospatial point clustering for browsers and Node.\n\n```js\nconst index = new Supercluster({radius: 40, maxZoom: 16});\nindex.load(points);\n\nconst clusters = index.getClusters([-180, -85, 180, 85], 2);\n```\n\nClustering 6 million points in Leaflet:\n\n![clustering demo on an interactive Leaflet map](https://cloud.githubusercontent.com/assets/25395/11857351/43407b46-a40c-11e5-8662-e99ab1cd2cb7.gif)\n\nSupercluster was built to power clustering in [Mapbox GL JS](https://www.mapbox.com/mapbox-gljs). Read about how it works [on the Mapbox blog](https://blog.mapbox.com/clustering-millions-of-points-on-a-map-with-supercluster-272046ec5c97).\n\n## Install\n\nInstall using NPM (`npm install supercluster`) or Yarn (`yarn add supercluster`), then:\n\n```js\n// import as a ES module in Node\nimport Supercluster from 'supercluster';\n\n// import from a CDN in the browser:\nimport Supercluster from 'https://esm.run/supercluster';\n```\n\nOr use it with an ordinary script tag in the browser:\n\n```html\n\u003cscript src=\"https://unpkg.com/supercluster@8.0.0/dist/supercluster.min.js\"\u003e\u003c/script\u003e\n```\n\n## Methods\n\n#### `load(points)`\n\nLoads 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.\n\n#### `getClusters(bbox, zoom)`\n\nFor 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.\n\n#### `getTile(z, x, y)`\n\nFor 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.\n\n#### `getChildren(clusterId)`\n\nReturns the children of a cluster (on the next zoom level) given its id (`cluster_id` value from feature properties).\n\n#### `getLeaves(clusterId, limit = 10, offset = 0)`\n\nReturns all the points of a cluster (given its `cluster_id`), with pagination support:\n`limit` is the number of points to return (set to `Infinity` for all points),\nand `offset` is the amount of points to skip (for pagination).\n\n#### `getClusterExpansionZoom(clusterId)`\n\nReturns the zoom on which the cluster expands into several children (useful for \"click to zoom\" feature) given the cluster's `cluster_id`.\n\n## Options\n\n| Option     | Default | Description                                                       |\n|------------|---------|-------------------------------------------------------------------|\n| minZoom    | 0       | Minimum zoom level at which clusters are generated.               |\n| maxZoom    | 16      | Maximum zoom level at which clusters are generated.               |\n| minPoints  | 2       | Minimum number of points to form a cluster.                       |\n| radius     | 40      | Cluster radius, in pixels.                                        |\n| extent     | 512     | (Tiles) Tile extent. Radius is calculated relative to this value. |\n| nodeSize   | 64      | Size of the KD-tree leaf node. Affects performance.               |\n| log        | false   | Whether timing info should be logged.                             |\n| generateId | false   | Whether to generate ids for input features in vector tiles.       |\n\n### Property map/reduce options\n\nIn addition to the options above, Supercluster supports property aggregation with the following two options:\n\n- `map`: a function that returns cluster properties corresponding to a single point.\n- `reduce`: a reduce function that merges properties of two clusters into one.\n\nExample of setting up a `sum` cluster property that accumulates the sum of `myValue` property values:\n\n```js\nconst index = new Supercluster({\n    map: (props) =\u003e ({sum: props.myValue}),\n    reduce: (accumulated, props) =\u003e { accumulated.sum += props.sum; }\n});\n```\n\nThe `map`/`reduce` options must satisfy these conditions to work correctly:\n\n- `map` must return a new object, not existing `properties` of a point, otherwise it will get overwritten.\n- `reduce` must not mutate the second argument (`props`).\n\n## TypeScript\n\nInstall `@types/supercluster` for the TypeScript type definitions:\n\n```\nnpm install @types/supercluster --save-dev \n```\n\n## Developing Supercluster\n\n```\nnpm install       # install dependencies\nnpm run build     # generate dist/supercluster.js and dist/supercluster.min.js\nnpm test          # run tests\n```\n","funding_links":[],"categories":["JavaScript","Geospatial Library","Node.js","\u003e 1K ⭐️"],"sub_categories":["JavaScript"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fsupercluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapbox%2Fsupercluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fsupercluster/lists"}