Geohash grid aggregation #

A multi-bucket aggregation that groups geo_point values into geohash cells — the building block of map clustering. It answers “where are my documents concentrated?” in one request, handing the map a count per cell instead of thousands of individual markers.

How it works #

Each document’s point is encoded as a geohash string: base-32 characters produced by interleaving longitude and latitude bits over successively halved intervals. precision is the number of characters kept — 1–12, clamped, default 5 (cells of roughly 4.9 km × 4.9 km). The classic Amsterdam coordinate 52.374081, 4.912350 at precision 3 lands in cell u17.

Every distinct cell becomes one bucket keyed by its geohash string. Buckets are sorted by doc_count descending with a key-ascending tie-break, then truncated to size. Documents whose field carries no parseable point are skipped. Sub-aggregations run per cell over that cell’s documents — a geo_centroid under each bucket gives the map an exact marker position.

Examples #

Precision 2 (~1,250 km cells):

Bucket keys are geohash strings (wt, ws, …) — render them on a map tile layer. Over the 15 teaching places, precision 2 yields wt with 4 documents, ws and wx with 2 each, and seven single-document cells:

{
  ...
  "aggregations": {
    "cells": {
      "buckets": [
        { "key": "wt", "doc_count": 4 },
        { "key": "ws", "doc_count": 2 },
        { "key": "wx", "doc_count": 2 },
        { "key": "tz", "doc_count": 1 },
        ...
      ]
    }
  }
}

Cell sizes per precision (geohash cells shrink by alternately halving longitude and latitude, so even precisions are roughly twice as wide as tall):

Use cases #

• Map heat layers. Feed the bucket keys straight into a geohash overlay; the count per cell drives color intensity.
• Server-side clustering. At low precision you get continent-scale clusters; raising precision zooms the grid, the standard cluster-on-bounds pattern behind map UIs.
• Per-cell statistics. Nest metric sub-aggregations to carry the average price or event count of each cell alongside its count.
• Geo QA. A cell that unexpectedly dominates the counts flags a geotagging bias or a bulk import pinned to one coordinate.

Parameters for geohash_grid #

• field
  (Required, string) geo_point field you wish to aggregate.
• precision
  (Optional, integer, default: 5) Geohash precision 1–12; values outside the range are clamped.
• size
  (Optional, integer, default: 10000) Maximum buckets returned.
• aggs
  (Optional, object) Nested sub-aggregations, computed per cell.

Related #

• geotile_grid — the same grid idea in Web-Mercator z/x/y tile coordinates
• geo_distance — rings around a point instead of a grid
• geo_centroid — per-cell center for marker placement
• composite — paginated grids for dense fields