> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/mapbox-tiling-service/llms.txt)

# Clustering point features

This example provides an overview of how to use the Mapbox Tiling Service (MTS) to cluster points into regions and visualize the point data as clusters in a map.

> **Related content (tutorial): [Cluster point data with MTS](https://docs.mapbox.com/help/tutorials/cluster-point-data-with-mts/)**
> 
> For a full tutorial on how to process your own data and render the clustered tileset in a map, see the **Cluster point data with Mapbox Tiling Service** tutorial.

To cluster point data in a tileset, you must use the [Vector Recipe specification](https://docs.mapbox.com/mapbox-tiling-service/recipe-specification/vector/) on a [tileset source](https://docs.mapbox.com/mapbox-tiling-service/guides/tileset-sources/). The code snippet below shows the recipe used to create a tileset with clustered data in this example.

```json
{
    "version": 1,
    "layers": {
      "store-locations-clustered": {
        "minzoom": 0,
        "maxzoom": 9,
        "source": "mapbox://tileset-source/examples/store-locations-source",
        "features": {
          "attributes": {
            // highlight-start
            "set": { "count": 1 } // Sets the count property to 1 for each point feature
            // highlight-end
          }
        },
        "tiles": {
          "union": [
            {
              // highlight-start
              "group_by": [], // empty group_by to union all features
              "cluster": true, // enable clustering
              "region_count": 64, // number of regions to create
              "aggregate": { "count": "sum" } // sum the count property
              // highlight-end
            }
          ]
        }
      },
      "store-locations": {
        "minzoom": 10,
        "maxzoom": 14,
        "source": "mapbox://tileset-source/examples/store-locations-source"
      }
    }
   }
```

The finished tileset can be viewed in [the Data Workbench](https://console.mapbox.com/studio/data-workbench/examples.store-locations-clustering/). Exploring this data shows how it is clustered into regions that split (or join) into new regions as you zoom in and out.

[

![Data Workbench on clustered tileset](https://docs.mapbox.com/mapbox-tiling-service/assets/ideal-img/example-mts-clustering-tileset-explorer.525de82.480.png)

](https://console.mapbox.com/studio/data-workbench/examples.store-locations-clustering/)

Once your data is processed into a tileset, you can use Mapbox GL JS or one of the mobile Maps SDKs to style the clusters. If you were to log the returned point data from a click event in a renderer, from the tileset above, the returned point's GeoJSON would look like this:

```json
{
   type: "Feature",
   id:  7183393275474299,
   layer:  {  
       id: 'locations', 
       type: 'circle', 
       source: 'clustered-data', 
       source-layer: 'store-locations-clustered', 
       filter: ['has', 'count'],
       paint: {...}
   },
   // highlight-start
   properties : {
       count: 78
   },
   // highlight-end
   source: "clustered-data",
   sourceLayer:  "store-locations-clustered",
   state : {},
   tile: {
      z: 3, 
      x: 1, 
      y: 3, 
      key: 12848
   },
}
```

The cluster feature's properties include `count`, specifying how many point features from the original dataset it represents. The `count` property can be used to add a number label or for data driven styling.

The code snippet below shows how to add the clustered tileset to a web map and style it at runtime using `step` expressions, which leverage the `count` property to determine the color and size of the cluster circle.

```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Clustering point features</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.28.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.28.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
  const map = new mapboxgl.Map({
    // TO MAKE THE MAP APPEAR YOU MUST
    // ADD YOUR ACCESS TOKEN FROM
    // https://account.mapbox.com
    accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
    container: 'map',
    style: 'mapbox://styles/mapbox/dark-v11',
    zoom: 3,
    center: [-100.10899, 39.15742]
  });

  map.on('load', () => {
    map.addSource('clustered-data', {
      type: 'vector',
      // Load our custom tileset as a vector source
      // Formatted as 'mapbox://{username}.{tileset-id}'
      url: 'mapbox://examples.cafe-locations-clustered'
    });

    map.addLayer({
      id: 'locations',
      type: 'circle',
      source: 'clustered-data',
      // 'source-layer' must reference the layer within the tileset that contains the clustered data
      'source-layer': 'locations',
      filter: ['has', 'count'],
      paint: {
        // The circle-color value uses a step expression to change the color of the cluster based on the count - more about step expressions https://docs.mapbox.com/style-spec/reference/expressions/#step
        'circle-color': [
          'step',
          ['get', 'count'],
          '#51bbd6',
          10,
          '#f1f075',
          20,
          '#f28cb1',
          75,
          '#ac41bf'
        ],
        'circle-opacity': 0.8,
        // The circle-radius value uses a step expression to change the size of the circle based on the count
        'circle-radius': [
          'step',
          ['get', 'count'],
          5,
          2,
          12,
          10,
          17,
          20,
          25,
          50,
          32,
          100,
          36
        ]
      }
    });

    map.addLayer({
      id: 'cluster-count',
      type: 'symbol',
      source: 'clustered-data',
      'source-layer': 'locations',
      filter: ['>', ['get', 'count'], 1],
      layout: {
        'text-field': ['get', 'count'],
        'text-font': ['DIN Offc Pro Medium', 'Arial Unicode MS Bold'],
        'text-size': 14
      }
    });
  });
</script>

</body>
</html>
```