GeoTile Grid Aggregation
editGeoTile Grid Aggregation
editA multi-bucket aggregation that works on geo_point
fields and groups points into
buckets that represent cells in a grid. The resulting grid can be sparse and only
contains cells that have matching data. Each cell corresponds to a
map tile as used by many online map
sites. Each cell is labeled using a "{zoom}/{x}/{y}" format, where zoom is equal
to the user-specified precision.
- High precision keys have a larger range for x and y, and represent tiles that cover only a small area.
- Low precision keys have a smaller range for x and y, and represent tiles that each cover a large area.
See Zoom level documentation on how precision (zoom) correlates to size on the ground. Precision for this aggregation can be between 0 and 29, inclusive.
The highest-precision geotile of length 29 produces cells that cover less than a 10cm by 10cm of land and so high-precision requests can be very costly in terms of RAM and result sizes. Please see the example below on how to first filter the aggregation to a smaller geographic area before requesting high-levels of detail.
The specified field must be of type geo_point
(which can only be set
explicitly in the mappings) and it can also hold an array of geo_point
fields, in which case all points will be taken into account during aggregation.
Simple low-precision request
editPUT /museums { "mappings": { "properties": { "location": { "type": "geo_point" } } } } POST /museums/_bulk?refresh {"index":{"_id":1}} {"location": "52.374081,4.912350", "name": "NEMO Science Museum"} {"index":{"_id":2}} {"location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis"} {"index":{"_id":3}} {"location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum"} {"index":{"_id":4}} {"location": "51.222900,4.405200", "name": "Letterenhuis"} {"index":{"_id":5}} {"location": "48.861111,2.336389", "name": "Musée du Louvre"} {"index":{"_id":6}} {"location": "48.860000,2.327000", "name": "Musée d'Orsay"} POST /museums/_search?size=0 { "aggregations" : { "large-grid" : { "geotile_grid" : { "field" : "location", "precision" : 8 } } } }
Response:
{ ... "aggregations": { "large-grid": { "buckets": [ { "key" : "8/131/84", "doc_count" : 3 }, { "key" : "8/129/88", "doc_count" : 2 }, { "key" : "8/131/85", "doc_count" : 1 } ] } } }
High-precision requests
editWhen requesting detailed buckets (typically for displaying a "zoomed in" map) a filter like geo_bounding_box should be applied to narrow the subject area otherwise potentially millions of buckets will be created and returned.
POST /museums/_search?size=0 { "aggregations" : { "zoomed-in" : { "filter" : { "geo_bounding_box" : { "location" : { "top_left" : "52.4, 4.9", "bottom_right" : "52.3, 5.0" } } }, "aggregations":{ "zoom1":{ "geotile_grid" : { "field": "location", "precision": 22 } } } } } }
{ ... "aggregations" : { "zoomed-in" : { "doc_count" : 3, "zoom1" : { "buckets" : [ { "key" : "22/2154412/1378379", "doc_count" : 1 }, { "key" : "22/2154385/1378332", "doc_count" : 1 }, { "key" : "22/2154259/1378425", "doc_count" : 1 } ] } } } }
Options
edit
field |
Mandatory. The name of the field indexed with GeoPoints. |
precision |
Optional. The integer zoom of the key used to define cells/buckets in the results. Defaults to 7. Values outside of [0,29] will be rejected. |
size |
Optional. The maximum number of geohash buckets to return (defaults to 10,000). When results are trimmed, buckets are prioritised based on the volumes of documents they contain. |
shard_size |
Optional. To allow for more accurate counting of the top cells
returned in the final result the aggregation defaults to
returning |