You're viewing version 2.19 of the OpenSearch documentation. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Geobounds aggregation
The geo_bounds aggregation is a multi-value aggregation that calculates the geographic bounding box encompassing a set of geo_point or geo_shape objects. The bounding box is returned as the upper-left and lower-right vertices of the rectangle given as a decimal-encoded latitude-longitude (lat-lon) pair.
Parameters
The geo_bounds aggregation takes the following parameters.
| Parameter | Required/Optional | Data type | Description |
|---|---|---|---|
field | Required | String | The name of the field containing the geopoints or geoshapes for which the geobounds are computed. |
wrap_longitude | Optional | Boolean | Whether to allow the bounding box to overlap the international date line. Default is true. |
Example
The following example returns the geo_bounds for the geoip.location of every order in the e-commerce sample data (each geoip.location is a geopoint):
GET opensearch_dashboards_sample_data_ecommerce/_search
{
"size": 0,
"aggs": {
"geo": {
"geo_bounds": {
"field": "geoip.location"
}
}
}
}
Example response
As shown in the following example response, the aggregation returns the geobounds containing all geopoints in the geoip.location field:
{
"took": 16,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 4675,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"geo": {
"bounds": {
"top_left": {
"lat": 52.49999997206032,
"lon": -118.20000001229346
},
"bottom_right": {
"lat": 4.599999985657632,
"lon": 55.299999956041574
}
}
}
}
}
Aggregating geoshapes
You can run a geo_bounds aggregation on geoshapes.
Prepare an example by inserting an index containing a geoshape field:
PUT national_parks
{
"mappings": {
"properties": {
"location": {
"type": "geo_shape"
}
}
}
}
Ingest documents into the index. GeoJSON input specifies longitude first:
POST _bulk
{ "create": { "_index": "national_parks", "_id": "1" } }
{"name": "Yellowstone National Park", "location": {"type": "envelope","coordinates": [ [-111.15, 45.12], [-109.83, 44.12] ]}}
{ "create": { "_index": "national_parks", "_id": "2" } }
{ "name": "Yosemite National Park", "location": {"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]} }
{ "create": { "_index": "national_parks", "_id": "3" } }
{ "name": "Death Valley National Park", "location": {"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]} }
{ "create": { "_index": "national_parks", "_id": "4" } }
{ "name": "War In The Pacific National Historic Park Guam", "location": {"type": "point","coordinates": [144.72, 13.47]} }
Run a geo_bounds aggregation on the location field:
GET national_parks/_search
{
"size": 0,
"aggregations": {
"grouped": {
"geo_bounds": {
"field": "location",
"wrap_longitude": true
}
}
}
}
The response contains the smallest geo-bounding box that encloses all shapes in the location field:
{
"took": 8,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 4,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"grouped": {
"bounds": {
"top_left": {
"lat": 45.11999997776002,
"lon": 144.71999991685152
},
"bottom_right": {
"lat": 13.469999986700714,
"lon": -109.83000006526709
}
}
}
}
}
Wrapping longitude
If the optional wrap_longitude parameter is set to true, the bounding box can overlap the international date line (180° meridian) and return a bounds object in which the upper-left longitude is greater than the lower-right longitude. The default value for wrap_longitude is true.
Rerun the geo_bounds aggregation on the national parks geoshape with wrap_longitude set to false:
GET national_parks/_search
{
"size": 0,
"aggregations": {
"grouped": {
"geo_bounds": {
"field": "location",
"wrap_longitude": false
}
}
}
}
Note that the new resulting geobound encompasses a larger area to avoid overlapping the dateline:
{
...
"aggregations": {
"grouped": {
"bounds": {
"top_left": {
"lat": 45.11999997776002,
"lon": -120.23000006563962
},
"bottom_right": {
"lat": 13.469999986700714,
"lon": 144.71999991685152
}
}
}
}
}
OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations.