You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `geo_bounds`metric is a multi-value metric aggregation that calculates the [geographic bounding box](https://docs.ogc.org/is/12-063r5/12-063r5.html#30)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.
12
+
The `geo_bounds`aggregation is a multi-value aggregation that calculates the [geographic bounding box](https://docs.ogc.org/is/12-063r5/12-063r5.html#30)encompassing a set of [`geo_point`](https://opensearch.org/docs/latest/field-types/supported-field-types/geo-point/) or [`geo_shape`](https://opensearch.org/docs/latest/field-types/supported-field-types/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.
13
13
14
-
The following example returns the `geo_bounds` metrics for the `geoip.location` field:
14
+
## Parameters
15
+
16
+
The `geo_bounds` aggregation takes the following parameters.
17
+
18
+
| Parameter | Required/Optional | Data type | Description |
19
+
| :-- | :-- | :-- | :-- |
20
+
|`field`| Required | String | The name of the field containing the geopoints or geoshapes for which the geobounds are computed. |
21
+
|`wrap_longitude`| Optional | Boolean | Whether to allow the bounding box to overlap the international date line. Default is `true`. |
22
+
23
+
## Example
24
+
25
+
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):
15
26
16
27
```json
17
28
GET opensearch_dashboards_sample_data_ecommerce/_search
@@ -26,30 +37,52 @@ GET opensearch_dashboards_sample_data_ecommerce/_search
26
37
}
27
38
}
28
39
```
40
+
{% include copy-curl.html %}
41
+
42
+
## Example response
29
43
30
-
#### Example response
44
+
As shown in the following example response, the aggregation returns the `geobounds` containing all geopoints in the `geoip.location` field:
31
45
32
46
```json
33
-
"aggregations" : {
34
-
"geo" : {
35
-
"bounds" : {
36
-
"top_left" : {
37
-
"lat" : 52.49999997206032,
38
-
"lon" : -118.20000001229346
39
-
},
40
-
"bottom_right" : {
41
-
"lat" : 4.599999985657632,
42
-
"lon" : 55.299999956041574
47
+
{
48
+
"took": 16,
49
+
"timed_out": false,
50
+
"_shards": {
51
+
"total": 1,
52
+
"successful": 1,
53
+
"skipped": 0,
54
+
"failed": 0
55
+
},
56
+
"hits": {
57
+
"total": {
58
+
"value": 4675,
59
+
"relation": "eq"
60
+
},
61
+
"max_score": null,
62
+
"hits": []
63
+
},
64
+
"aggregations": {
65
+
"geo": {
66
+
"bounds": {
67
+
"top_left": {
68
+
"lat": 52.49999997206032,
69
+
"lon": -118.20000001229346
70
+
},
71
+
"bottom_right": {
72
+
"lat": 4.599999985657632,
73
+
"lon": 55.299999956041574
74
+
}
43
75
}
44
76
}
45
77
}
46
-
}
47
78
}
48
79
```
49
80
50
81
## Aggregating geoshapes
51
82
52
-
To run an aggregation on a geoshape field, first create an index and map the `location` field as a `geo_shape`:
83
+
You can run a `geo_bounds` aggregation on geoshapes.
84
+
85
+
Prepare an example by inserting an index containing a geoshape field:
53
86
54
87
```json
55
88
PUT national_parks
@@ -65,164 +98,119 @@ PUT national_parks
65
98
```
66
99
{% include copy-curl.html %}
67
100
68
-
Next, index some documents into the `national_parks`index:
101
+
Ingest documents into the index. GeoJSON input specifies longitude first:
You can run a `geo_bounds` aggregation on the `location` field as follows:
171
+
## Wrapping longitude
172
+
173
+
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`.
174
+
175
+
Rerun the `geo_bounds` aggregation on the national parks geoshape with `wrap_longitude` set to `false`:
101
176
102
177
```json
103
178
GET national_parks/_search
104
179
{
180
+
"size": 0,
105
181
"aggregations": {
106
182
"grouped": {
107
183
"geo_bounds": {
108
184
"field": "location",
109
-
"wrap_longitude": true
185
+
"wrap_longitude": false
110
186
}
111
187
}
112
188
}
113
189
}
114
190
```
115
191
{% include copy-curl.html %}
116
192
117
-
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`.
118
-
119
-
The response contains the geo-bounding box that encloses all shapes in the `location` field:
120
-
121
-
<detailsopenmarkdown="block">
122
-
<summary>
123
-
Response
124
-
</summary>
125
-
{: .text-delta}
193
+
Note that the new resulting geobound encompasses a larger area to avoid overlapping the dateline:
126
194
127
195
```json
128
196
{
129
-
"took" : 3,
130
-
"timed_out" : false,
131
-
"_shards" : {
132
-
"total" : 1,
133
-
"successful" : 1,
134
-
"skipped" : 0,
135
-
"failed" : 0
136
-
},
137
-
"hits" : {
138
-
"total" : {
139
-
"value" : 3,
140
-
"relation" : "eq"
141
-
},
142
-
"max_score" : 1.0,
143
-
"hits" : [
144
-
{
145
-
"_index" : "national_parks",
146
-
"_id" : "1",
147
-
"_score" : 1.0,
148
-
"_source" : {
149
-
"name" : "Yellowstone National Park",
150
-
"location" : {
151
-
"type" : "envelope",
152
-
"coordinates" : [
153
-
[
154
-
-111.15,
155
-
45.12
156
-
],
157
-
[
158
-
-109.83,
159
-
44.12
160
-
]
161
-
]
162
-
}
163
-
}
164
-
},
165
-
{
166
-
"_index" : "national_parks",
167
-
"_id" : "2",
168
-
"_score" : 1.0,
169
-
"_source" : {
170
-
"name" : "Yosemite National Park",
171
-
"location" : {
172
-
"type" : "envelope",
173
-
"coordinates" : [
174
-
[
175
-
-120.23,
176
-
38.16
177
-
],
178
-
[
179
-
-119.05,
180
-
37.45
181
-
]
182
-
]
183
-
}
184
-
}
185
-
},
186
-
{
187
-
"_index" : "national_parks",
188
-
"_id" : "3",
189
-
"_score" : 1.0,
190
-
"_source" : {
191
-
"name" : "Death Valley National Park",
192
-
"location" : {
193
-
"type" : "envelope",
194
-
"coordinates" : [
195
-
[
196
-
-117.34,
197
-
37.01
198
-
],
199
-
[
200
-
-116.38,
201
-
36.25
202
-
]
203
-
]
204
-
}
205
-
}
206
-
}
207
-
]
208
-
},
209
-
"aggregations" : {
210
-
"Grouped" : {
211
-
"bounds" : {
212
-
"top_left" : {
213
-
"lat" : 45.11999997776002,
214
-
"lon" : -120.23000006563962
197
+
...
198
+
"aggregations": {
199
+
"grouped": {
200
+
"bounds": {
201
+
"top_left": {
202
+
"lat": 45.11999997776002,
203
+
"lon": -120.23000006563962
215
204
},
216
-
"bottom_right": {
217
-
"lat" : 36.249999976716936,
218
-
"lon" : -109.83000006526709
205
+
"bottom_right": {
206
+
"lat": 13.469999986700714,
207
+
"lon": 144.71999991685152
219
208
}
220
209
}
221
210
}
222
211
}
223
212
}
224
213
```
225
-
</details>
226
214
227
-
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](https://github.com/opensearch-project/dashboards-maps/issues/250).
215
+
OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations.
0 commit comments