Geobounds aggregations

The geo_bounds metric is a multi-value metric aggregation that calculates the geographic bounding box containing all values of a given geo_point or geo_shape field. The bounding box is returned as the upper-left and lower-right vertices of the rectangle in terms of latitude and longitude.

The following example returns the geo_bounds metrics for the geoip.location field:

  1. GET opensearch_dashboards_sample_data_ecommerce/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "geo": {
  6.       "geo_bounds": {
  7.         "field": "geoip.location"
  8.       }
  9.     }
  10.   }
  11. }

Example response

  1. "aggregations" : {
  2.   "geo" : {
  3.     "bounds" : {
  4.       "top_left" : {
  5.         "lat" : 52.49999997206032,
  6.         "lon" : -118.20000001229346
  7.       },
  8.       "bottom_right" : {
  9.         "lat" : 4.599999985657632,
  10.         "lon" : 55.299999956041574
  11.       }
  12.     }
  13.   }
  14.  }
  15. }

Aggregating geoshapes

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

  1. PUT national_parks
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "location": {
  6.         "type": "geo_shape"
  7.       }
  8.     }
  9.   }
  10. }

copy

Next, index some documents into the national_parks index:

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

copy

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

copy

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

copy

You can run a geo_bounds aggregation on the location field as follows:

  1. GET national_parks/_search
  2. {
  3.   "aggregations": {
  4.     "grouped": {
  5.       "geo_bounds": {
  6.         "field": "location",
  7.         "wrap_longitude": true
  8.       }
  9.     }
  10.   }
  11. }

copy

The optional wrap_longitude parameter specifies whether the bounding box returned by the aggregation can overlap the international date line (180° meridian). If wrap_longitude is set to true, the bounding box can overlap the international date line and return a bounds object in which the lower-left longitude is greater than the upper-right longitude. The default value for wrap_longitude is true.

The response contains the geo-bounding box that encloses all shapes in the location field:

Response

  1. {
  2.   "took" : 3,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 3,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "national_parks",
  19.         "_id" : "1",
  20.         "_score" : 1.0,
  21.         "_source" : {
  22.           "name" : "Yellowstone National Park",
  23.           "location" : {
  24.             "type" : "envelope",
  25.             "coordinates" : [
  26.               [
  27.                 -111.15,
  28.                 45.12
  29.               ],
  30.               [
  31.                 -109.83,
  32.                 44.12
  33.               ]
  34.             ]
  35.           }
  36.         }
  37.       },
  38.       {
  39.         "_index" : "national_parks",
  40.         "_id" : "2",
  41.         "_score" : 1.0,
  42.         "_source" : {
  43.           "name" : "Yosemite National Park",
  44.           "location" : {
  45.             "type" : "envelope",
  46.             "coordinates" : [
  47.               [
  48.                 -120.23,
  49.                 38.16
  50.               ],
  51.               [
  52.                 -119.05,
  53.                 37.45
  54.               ]
  55.             ]
  56.           }
  57.         }
  58.       },
  59.       {
  60.         "_index" : "national_parks",
  61.         "_id" : "3",
  62.         "_score" : 1.0,
  63.         "_source" : {
  64.           "name" : "Death Valley National Park",
  65.           "location" : {
  66.             "type" : "envelope",
  67.             "coordinates" : [
  68.               [
  69.                 -117.34,
  70.                 37.01
  71.               ],
  72.               [
  73.                 -116.38,
  74.                 36.25
  75.               ]
  76.             ]
  77.           }
  78.         }
  79.       }
  80.     ]
  81.   },
  82.   "aggregations" : {
  83.     "Grouped" : {
  84.       "bounds" : {
  85.         "top_left" : {
  86.           "lat" : 45.11999997776002,
  87.           "lon" : -120.23000006563962
  88.         },
  89.         "bottom_right" : {
  90.           "lat" : 36.249999976716936,
  91.           "lon" : -109.83000006526709
  92.         }
  93.       }
  94.     }
  95.   }
  96. }

Currently, OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations. If you’d like to see geoshape aggregation implemented for visualizations, upvote the related GitHub issue.