Geohash grid aggregations

The geohash_grid aggregation groups documents into grid cells based on their geohash value. Each cell is labeled with its geohash string, and the precision parameter controls cell size—lower precision values produce fewer, larger cells, while higher values produce many smaller cells. You can aggregate documents on geo_point or geo_shape fields. A geo_point is placed in exactly one cell, while a geo_shape is counted in every cell it intersects.

Precision values range from 1 to 12. High-precision requests can consume significant memory and produce large responses because they generate many buckets. Filter to a small geographic area before using high precision values.

Parameters

The geohash_grid aggregation takes the following parameters.

Example: Low-precision grid

The following example groups ecommerce customer locations into geohash cells at precision 4 (approximately 39 km × 19.5 km):

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "geo_hash": {
      "geohash_grid": {
        "field": "geoip.location",
        "precision": 4
      }
    }
  }
}

Example: High-precision grid with bounding box filter

When zooming into a specific region, first filter documents to that area before requesting high precision. The following example uses a geo_bounding_box query to narrow to the New York City area, then aggregates at precision 7 (approximately 153 m × 152 m):

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "zoomed_in": {
      "filter": {
        "geo_bounding_box": {
          "geoip.location": {
            "top_left": "41.0, -74.5",
            "bottom_right": "40.5, -73.5"
          }
        }
      },
      "aggs": {
        "detailed_grid": {
          "geohash_grid": {
            "field": "geoip.location",
            "precision": 7
          }
        }
      }
    }
  }
}

Example response

The following response corresponds to the high-precision example:

{
  "took": 23,
  "timed_out": false,
  "terminated_early": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "zoomed_in": {
      "doc_count": 896,
      "detailed_grid": {
        "buckets": [
          {
            "key": "dr72h56",
            "doc_count": 747
          },
          {
            "key": "dr5rs14",
            "doc_count": 149
          }
        ]
      }
    }
  }
}

Response body fields

The following table lists the response body fields.

You can use a returned geohash key as both the top_left and bottom_right of a geo_bounding_box query to zoom into that cell at a higher precision. Client-side geohash libraries (such as ngeohash for JavaScript) can decode bucket keys into lat/lon bounding boxes for map rendering.

Aggregating geoshapes

To run an aggregation on a geoshape field, first create an index and map the location field as a geo_shape:

PUT /national_parks
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_shape"
      }
    }
  }
}

Next, index some documents into the national_parks index:

PUT /national_parks/_doc/1
{
  "name": "Yellowstone National Park",
  "location":
  {"type": "envelope","coordinates": [ [-111.15, 45.12], [-109.83, 44.12] ]}
}

PUT /national_parks/_doc/2
{
  "name": "Yosemite National Park",
  "location": 
  {"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]}
}

PUT /national_parks/_doc/3
{
  "name": "Death Valley National Park",
  "location": 
  {"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]}
}

You can run an aggregation on the location field as follows:

GET /national_parks/_search
{
  "aggregations": {
    "grouped": {
      "geohash_grid": {
        "field": "location",
        "precision": 1
      }
    }
  }
}

A geoshape can appear in multiple buckets when it spans more than one grid cell:

{
  "took" : 24,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "national_parks",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "name" : "Yellowstone National Park",
          "location" : {
            "type" : "envelope",
            "coordinates" : [
              [
                -111.15,
                45.12
              ],
              [
                -109.83,
                44.12
              ]
            ]
          }
        }
      },
      {
        "_index" : "national_parks",
        "_id" : "2",
        "_score" : 1.0,
        "_source" : {
          "name" : "Yosemite National Park",
          "location" : {
            "type" : "envelope",
            "coordinates" : [
              [
                -120.23,
                38.16
              ],
              [
                -119.05,
                37.45
              ]
            ]
          }
        }
      },
      {
        "_index" : "national_parks",
        "_id" : "3",
        "_score" : 1.0,
        "_source" : {
          "name" : "Death Valley National Park",
          "location" : {
            "type" : "envelope",
            "coordinates" : [
              [
                -117.34,
                37.01
              ],
              [
                -116.38,
                36.25
              ]
            ]
          }
        }
      }
    ]
  },
  "aggregations" : {
    "grouped" : {
      "buckets" : [
        {
          "key" : "9",
          "doc_count" : 3
        },
        {
          "key" : "c",
          "doc_count" : 1
        }
      ]
    }
  }
}

OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations.

Geohash precision

The following table lists the approximate cell dimensions at each precision level. Cell dimensions vary with latitude; the values shown represent the widest case at the equator.