Clustered Data

When displaying many points, clustering improves performance and readability.

Live Demo

Zoom in to see individual points

Key Concepts

Enable clustering

Configure clustering on the GeoJSON source:

source:
  id: quakes                # Named source for reuse
  type: geojson
  url: "..."
  cluster: true             # Enable clustering
  clusterRadius: 50         # Cluster radius in pixels
  clusterMaxZoom: 14        # Don't cluster above zoom 14

Multiple layers from one source

Three layers reference the same source:

layers:
  # Layer 1: Cluster circles
  - id: clusters
    source: quakes
    filter: ["has", "point_count"]    # Only clusters

  # Layer 2: Cluster counts
  - id: cluster-count
    source: quakes
    filter: ["has", "point_count"]    # Only clusters

  # Layer 3: Individual points
  - id: unclustered
    source: quakes
    filter: ["!", ["has", "point_count"]]    # Only points

Step expressions for cluster size

Cluster size increases with point count:

circle-radius:
  - step
  - ["get", "point_count"]
  - 20       # < 100 points: 20px radius
  - 100
  - 30       # 100-749 points: 30px radius
  - 750
  - 40       # 750+ points: 40px radius

Step expressions for cluster color

Cluster color changes with point count:

circle-color:
  - step
  - ["get", "point_count"]
  - "#51bbd6"    # < 100 points: blue
  - 100
  - "#f1f075"    # 100-749 points: yellow
  - 750
  - "#f28cb1"    # 750+ points: pink

Filter expressions

["has", "point_count"] - Match only clusters
["!", ["has", "point_count"]] - Match only individual points

Performance benefits

Clustering provides:

Faster rendering: Fewer features to draw at low zoom levels
Clearer visualization: Avoids visual clutter from overlapping points
Better UX: Users can zoom in to see detail where needed