Geotile grid aggregation #

A multi-bucket aggregation grouping geo_point values into zoom/x/y map tiles — the native grid of web maps. Where geohash_grid speaks in geohash strings, this one emits exactly the tile addresses a Leaflet/MapLibre layer already understands, so clustering needs no coordinate translation.

How it works #

Each point is mapped to its Web-Mercator tile: x and y are computed from longitude/latitude scaled by 2^zoom, latitude clamped to the projection’s ±85.0511° limit. precision is the zoom level — 0–29, default 7 (a tile spans ~300 km at the equator; each zoom step halves it). The bucket key is the z/x/y string, e.g. Amsterdam at zoom 8 → 8/131/84.

Buckets are sorted by doc_count descending with a key-ascending tie-break, then truncated to size. Points outside the field are skipped, and sub-aggregations run per tile. The same tile grid is also available as a composite source when the grid is too dense for one page.

Examples #

Zoom 5 tiles:

Keys like 5/26/13 address the tile at zoom 5, column 26, row 13. Over the 15 teaching places, zoom 5 puts 6 documents in 5/26/13, 2 each in 5/25/13 and 5/26/12, and 1 in each of five more tiles:

{
  ...
  "aggregations": {
    "tiles": {
      "buckets": [
        { "key": "5/26/13", "doc_count": 6 },
        { "key": "5/25/13", "doc_count": 2 },
        { "key": "5/26/12", "doc_count": 2 },
        { "key": "5/23/11", "doc_count": 1 },
        ...
      ]
    }
  }
}

A tile spans 360° / 2^zoom of longitude — about 1,250 km at the equator at zoom 5, 300 km at the default zoom 7, 1.2 km at zoom 12 — and shrinks toward the poles exactly as Mercator tiles do, so the bucket counts line up with what the rendered map shows.

Use cases #

• Tile-server clustering. The keys line up one-to-one with map tiles; drop counts into the layer and the map clusters itself.
• Zoom-aware dashboards. Match precision to the map’s current zoom so the grid resolution always tracks what the user sees.
• Regional rollups. Low zooms (0–4) give country-scale buckets for headline stats; sub-aggregations carry per-tile sums and averages.
• Viewport prefetch. Request one zoom above the current view to precompute the clusters revealed by the next zoom-in.

Parameters for geotile_grid #

• field
  (Required, string) geo_point field you wish to aggregate.
• precision
  (Optional, integer, default: 7) Tile zoom 0–29; higher values are clamped to 29.
• size
  (Optional, integer, default: 10000) Maximum buckets returned.
• aggs
  (Optional, object) Nested sub-aggregations, computed per tile.

Related #

• geohash_grid — the same grid in geohash cell coordinates
• geo_distance — rings around a point instead of a grid
• composite — paginated geotile_grid source for dense fields
• geo_bounds — bounding box of the points, handy for picking the zoom