Starting today, customers can now cluster tiled data directly via the Mapbox Tiling Service (MTS) using recipe features. Developers no longer need to pre-cluster source data or use legacy tools like Tippecanoe to create clustered tilesets. The new clustering capability of MTS makes it easier to consolidate and streamline data pipelines.

Visualize high point count, low zoom level datasets

MTS clustering enables cluster circle and heatmap data visualizations for high point count, low zoom level datasets without dropped or missing features. This makes it easier to avoid hitting layer size limits at lower zoom levels for high-point count datasets. For example, developers can create circle clusters of available parking spots for an entire continent or large country at zoom level 4. Developers could also create a heatmap of the value of their real estate portfolio across the entire United States that’s visible even at zoom level 3, with no missing properties.

Real estate organizations could cluster their national listings database in internal dashboards to help with analysis. Travel planning sites could cluster hotel listings by city or country to give users a bird’s eye view of hotel availability when planning a trip.

There are two steps to creating a cluster data visualization using MTS:

Step 1: Cluster data with MTS

To cluster data with MTS:

1. Set a count feature attribute with a value of 1 for each point
2. Configure the cluster field in the tiles configuration

Step 1 - Set the count feature attribute

First, add a feature attribute called count to the feature configuration of your MTS recipe. Set the value of this feature attribute to 1. MTS will sum each point to create the cluster point count.

{
  "version": 1,
  "layers": {
    "locations": {
      "minzoom": 0,
      "maxzoom": 12,
      "source": "mapbox://tileset-source/{username}/{id}",
      "features": {
        "attributes": {
          "set": { "count": 1 }
        }
      }
    }
  }
}

Step 2 - Union points via clustering

Second, add a union object to the tile configuration of the MTS recipe and set cluster to true. Use an empty group_by ("group_by": []) to union all features (e.g., points to be clustered) regardless of their attributes. Set the region_count to the number of clustered points needed for each tile. The region_count must be a power of 4 between 1 and 16,384, so valid values are 1, 4, 16, 64, 256, 1024, 4096, or 16384.

Finally, use an aggregate rule to sum the count for each point to create the point count for the cluster. It’s possible to add additional aggregate rules here for other feature attributes to use in clustering or heatmap data visualizations. For example, calculate the total property value for a real estate footprint dataset or the total population for a cities dataset.

"tiles": {
  "union": [
    {
      "group_by": [],
      "cluster": true,
      "region_count": 64,
      "aggregate": { "count": "sum" }
    }
  ]
}

Final recipe

The final clustering MTS recipe will look like this:

{
  "version": 1,
  "layers": {
    "locations": {
      "minzoom": 0,
      "maxzoom": 12,
      "source": "mapbox://tileset-source/{username}/{id}",
      "features": {
        "attributes": {
          "set": { "count": 1 }
        }
      },
      "tiles": {
        "union": [
          {
            "group_by": [],
            "cluster": true,
            "region_count": 64,
            "aggregate": { "count": "sum" }
          }
        ]
      }
    }
  }
}

Step 2: Style clustered data

After publishing the tileset, there will be a set of evenly spaced points in the Tileset Explorer. While these points do not look like clusters yet, the data is structured to enable data-driven styling with just a few additional steps.

To create clusters, use data-driven styling with either a circle layer or a heatmap layer. A circle layer creates a traditional cluster map with different-sized and colored circles based on the point count of a cluster. Or use a heatmap layer instead, which uses a range of colors to show density.

The code samples below use Mapbox GL JS. Mapbox Studio and the Mapbox Mobile Maps SDKs for iOS and Android also support creating circle and heatmap layers.

Create a traditional cluster circle layer with data-driven styling

The Mapbox GL JS code sample below uses data-driven styling of a circle layer using the point count of the cluster. Clusters with a point count of 2 or less are blue circles with a 3px radius, point counts between 2-10 are yellow circles with a 5px radius, and point counts of 10 or greater are pink circles with a 10 px radius.

map.addLayer({
  id: "locations",
  type: "circle",
  source: "locations",
  "source-layer": "locations",
  filter: ["has", "count"],
  paint: {
    "circle-color": [
      "step",
      ["get", "count"],
      "#51bbd6",
      2,
      "#f1f075",
      10,
      "#f28cb1",
    ],
    "circle-radius": ["step", ["get", "count"], 3, 2, 5, 10, 10],
  },
});

Create a heatmap with clustered tileset data

The Mapbox GL JS code sample below uses a heatmap layer to display clustered points. The Make a heatmap with Mapbox GL JS tutorial describes in depth how to modify the heatmap paint properties for the data source.

map.addLayer(
  {
    id: "locations",
    type: "heatmap",
    source: "locations",
    "source-layer": "locations",
    maxzoom: 9,
    paint: {
      "heatmap-weight": [
        "interpolate",
        ["linear"],
        ["get", "count"],
        0,
        0,
        5,
        5
      ],
      // Increase the heatmap color weight by zoom level
      // heatmap-intensity is a multiplier on top of heatmap-weight
      "heatmap-intensity": ["interpolate", ["linear"], ["zoom"], 0, 1, 9, 3],
      // Color ramp for heatmap. Domain is 0 (low) to 1 (high).
      // Begin color ramp at 0-stop with a 0-transparency color
      // to create a blur-like effect.
      "heatmap-color": [
        "interpolate",
        ["linear"],
        ["heatmap-density"],
        0,
        "rgba(33,102,172,0)",
        0.2,
        "rgb(103,169,207)",
        0.4,
        "rgb(209,229,240)",
        0.6,
        "rgb(253,219,199)",
        0.8,
        "rgb(239,138,98)",
        1,
        "rgb(178,24,43)"
      ],
      // Adjust the heatmap radius by zoom level
      "heatmap-radius": ["interpolate", ["linear"], ["zoom"], 0, 20, 6, 40],
      // Transition from heatmap to circle layer by zoom level
      "heatmap-opacity": ["interpolate", ["linear"], ["zoom"], 7, 1, 9, 0]
    }
  },
  "waterway-label"
);

map.addLayer(
  {
    id: "locations-point",
    type: "circle",
    source: "locations",
    "source-layer": "locations",
    minzoom: 7,
    paint: {
      // Size circle radius by point count and zoom level
      "circle-radius": [
        "interpolate",
        ["linear"],
        ["zoom"],
        7,
        ["interpolate", ["linear"], ["get", "count"], 1, 1, 6, 4],
        16,
        ["interpolate", ["linear"], ["get", "count"], 1, 5, 6, 50]
      ],
      // Color circle by point count
      "circle-color": [
        "interpolate",
        ["linear"],
        ["get", "count"],
        1,
        "rgba(33,102,172,0)",
        2,
        "rgb(103,169,207)",
        3,
        "rgb(209,229,240)",
        4,
        "rgb(253,219,199)",
        5,
        "rgb(239,138,98)",
        6,
        "rgb(178,24,43)"
      ],
      "circle-stroke-color": "white",
      "circle-stroke-width": 1,
      // Transition from heatmap to circle layer by zoom level
      "circle-opacity": ["interpolate", ["linear"], ["zoom"], 7, 0, 8, 1]
    }
  },
  "waterway-label"
);

Consistently improving the Mapbox Tiling Service

MTS clustering is available today for all MTS customers at no additional cost. Check out the MTS documentation to learn more about MTS.

Clustering is one of many recent improvements to the Mapbox Tiling Service, including support for raster data and multi-region architecture for reliability and compliance. Check out the raster MTS documentation to get started. To learn more about multi-region MTS, email Mapbox at mts-multi-region@mapbox.com.