Search a vector tile Added in 7.15.0
Search a vector tile for geospatial values. Before using this API, you should be familiar with the Mapbox vector tile specification. The API returns results as a binary mapbox vector tile.
Internally, Elasticsearch translates a vector tile search API request into a search containing:
- A
geo_bounding_box
query on the<field>
. The query uses the<zoom>/<x>/<y>
tile as a bounding box. - A
geotile_grid
orgeohex_grid
aggregation on the<field>
. Thegrid_agg
parameter determines the aggregation type. The aggregation uses the<zoom>/<x>/<y>
tile as a bounding box. - Optionally, a
geo_bounds
aggregation on the<field>
. The search only includes this aggregation if theexact_bounds
parameter istrue
. - If the optional parameter
with_labels
istrue
, the internal search will include a dynamic runtime field that calls thegetLabelPosition
function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.
For example, Elasticsearch may translate a vector tile search API request with a grid_agg
argument of geotile
and an exact_bounds
argument of true
into the following search
GET my-index/_search
{
"size": 10000,
"query": {
"geo_bounding_box": {
"my-geo-field": {
"top_left": {
"lat": -40.979898069620134,
"lon": -45
},
"bottom_right": {
"lat": -66.51326044311186,
"lon": 0
}
}
}
},
"aggregations": {
"grid": {
"geotile_grid": {
"field": "my-geo-field",
"precision": 11,
"size": 65536,
"bounds": {
"top_left": {
"lat": -40.979898069620134,
"lon": -45
},
"bottom_right": {
"lat": -66.51326044311186,
"lon": 0
}
}
}
},
"bounds": {
"geo_bounds": {
"field": "my-geo-field",
"wrap_longitude": false
}
}
}
}
The API returns results as a binary Mapbox vector tile. Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:
- A
hits
layer containing a feature for each<field>
value matching thegeo_bounding_box
query. - An
aggs
layer containing a feature for each cell of thegeotile_grid
orgeohex_grid
. The layer only contains features for cells with matching data. - A meta layer containing:
- A feature containing a bounding box. By default, this is the bounding box of the tile.
- Value ranges for any sub-aggregations on the
geotile_grid
orgeohex_grid
. - Metadata for the search.
The API only returns features that can display at its zoom level. For example, if a polygon feature has no area at its zoom level, the API omits it. The API returns errors as UTF-8 encoded JSON.
IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. If you specify both parameters, the query parameter takes precedence.
Grid precision for geotile
For a grid_agg
of geotile
, you can use cells in the aggs
layer as tiles for lower zoom levels.
grid_precision
represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision
.
For example, if <zoom>
is 7 and grid_precision
is 8, then the geotile_grid
aggregation will use a precision of 15.
The maximum final precision is 29.
The grid_precision
also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision)
.
For example, a value of 8 divides the tile into a grid of 256 x 256 cells.
The aggs
layer only contains features for cells with matching data.
Grid precision for geohex
For a grid_agg
of geohex
, Elasticsearch uses <zoom>
and grid_precision
to calculate a final precision as follows: <zoom> + grid_precision
.
This precision determines the H3 resolution of the hexagonal cells produced by the geohex
aggregation.
The following table maps the H3 resolution for each precision.
For example, if <zoom>
is 3 and grid_precision
is 3, the precision is 6.
At a precision of 6, hexagonal cells have an H3 resolution of 2.
If <zoom>
is 3 and grid_precision
is 4, the precision is 7.
At a precision of 7, hexagonal cells have an H3 resolution of 3.
Precision | Unique tile bins | H3 resolution | Unique hex bins | Ratio |
---|---|---|---|---|
1 | 4 | 0 | 122 | 30.5 |
2 | 16 | 0 | 122 | 7.625 |
3 | 64 | 1 | 842 | 13.15625 |
4 | 256 | 1 | 842 | 3.2890625 |
5 | 1024 | 2 | 5882 | 5.744140625 |
6 | 4096 | 2 | 5882 | 1.436035156 |
7 | 16384 | 3 | 41162 | 2.512329102 |
8 | 65536 | 3 | 41162 | 0.6280822754 |
9 | 262144 | 4 | 288122 | 1.099098206 |
10 | 1048576 | 4 | 288122 | 0.2747745514 |
11 | 4194304 | 5 | 2016842 | 0.4808526039 |
12 | 16777216 | 6 | 14117882 | 0.8414913416 |
13 | 67108864 | 6 | 14117882 | 0.2103728354 |
14 | 268435456 | 7 | 98825162 | 0.3681524172 |
15 | 1073741824 | 8 | 691776122 | 0.644266719 |
16 | 4294967296 | 8 | 691776122 | 0.1610666797 |
17 | 17179869184 | 9 | 4842432842 | 0.2818666889 |
18 | 68719476736 | 10 | 33897029882 | 0.4932667053 |
19 | 274877906944 | 11 | 237279209162 | 0.8632167343 |
20 | 1099511627776 | 11 | 237279209162 | 0.2158041836 |
21 | 4398046511104 | 12 | 1660954464122 | 0.3776573213 |
22 | 17592186044416 | 13 | 11626681248842 | 0.6609003122 |
23 | 70368744177664 | 13 | 11626681248842 | 0.165225078 |
24 | 281474976710656 | 14 | 81386768741882 | 0.2891438866 |
25 | 1125899906842620 | 15 | 569707381193162 | 0.5060018015 |
26 | 4503599627370500 | 15 | 569707381193162 | 0.1265004504 |
27 | 18014398509482000 | 15 | 569707381193162 | 0.03162511259 |
28 | 72057594037927900 | 15 | 569707381193162 | 0.007906278149 |
29 | 288230376151712000 | 15 | 569707381193162 | 0.001976569537 |
Hexagonal cells don't align perfectly on a vector tile. Some cells may intersect more than one vector tile. To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.
Path parameters
-
Comma-separated list of data streams, indices, or aliases to search
-
Field containing geospatial data to return
-
Zoom level for the vector tile to search
-
X coordinate for the vector tile to search
-
Y coordinate for the vector tile to search
Query parameters
-
exact_bounds boolean
If
false
, the meta layer's feature is the bounding box of the tile. If true, the meta layer's feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the // tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile. -
extent number
The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
grid_agg string
Aggregation used to create a grid for
field
.Values are
geotile
orgeohex
. -
grid_precision number
Additional zoom levels available through the aggs layer. For example, if is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer.
-
grid_type string
Determines the geometry type for features in the aggs layer. In the aggs layer, each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon of the cells bounding box. If 'point' each feature is a Point that is the centroid of the cell.
Values are
grid
,point
, orcentroid
. -
size number
Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
-
with_labels boolean
If
true
, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.Point
andMultiPoint
features will have one of the points selected.Polygon
andMultiPolygon
features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.LineString
features will likewise provide a roughly central point selected from the triangle-tree.- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag
_mvt_label_position
.
Body
-
aggs object
Sub-aggregations for the geotile_grid.
It supports the following aggregation types:
avg
boxplot
cardinality
extended stats
max
median absolute deviation
min
percentile
percentile-rank
stats
sum
value count
The aggregation names can't start with
_mvt_
. The_mvt_
prefix is reserved for internal aggregations. -
buffer number
The size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile.
-
exact_bounds boolean
If
false
, the meta layer's feature is the bounding box of the tile. Iftrue
, the meta layer's feature is a bounding box resulting from ageo_bounds
aggregation. The aggregation runs on values that intersect the<zoom>/<x>/<y>
tile withwrap_longitude
set tofalse
. The resulting bounding box may be larger than the vector tile. -
extent number
The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
fields string | array[string]
-
grid_agg string
Values are
geotile
orgeohex
. -
grid_precision number
Additional zoom levels available through the aggs layer. For example, if
<zoom>
is7
andgrid_precision
is8
, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer. -
grid_type string
Values are
grid
,point
, orcentroid
. -
query object
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Additional properties are allowed.
-
runtime_mappings object
-
size number
The maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
-
track_total_hits boolean | number
Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
-
with_labels boolean
If
true
, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.Point
andMultiPoint
features will have one of the points selected.Polygon
andMultiPolygon
features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.LineString
features will likewise provide a roughly central point selected from the triangle-tree.- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag
_mvt_label_position
.
curl \
--request POST http://api.example.com/{index}/_mvt/{field}/{zoom}/{x}/{y} \
--header "Content-Type: application/json" \
--data '"{\n \"grid_agg\": \"geotile\",\n \"grid_precision\": 2,\n \"fields\": [\n \"name\",\n \"price\"\n ],\n \"query\": {\n \"term\": {\n \"included\": true\n }\n },\n \"aggs\": {\n \"min_price\": {\n \"min\": {\n \"field\": \"price\"\n }\n },\n \"max_price\": {\n \"max\": {\n \"field\": \"price\"\n }\n },\n \"avg_price\": {\n \"avg\": {\n \"field\": \"price\"\n }\n }\n }\n}"'
{
"grid_agg": "geotile",
"grid_precision": 2,
"fields": [
"name",
"price"
],
"query": {
"term": {
"included": true
}
},
"aggs": {
"min_price": {
"min": {
"field": "price"
}
},
"max_price": {
"max": {
"field": "price"
}
},
"avg_price": {
"avg": {
"field": "price"
}
}
}
}
{
"hits": {
"extent": 4096,
"version": 2,
"features": [
{
"geometry": {
"type": "Point",
"coordinates": [
3208,
3864
]
},
"properties": {
"_id": "1",
"_index": "museums",
"name": "NEMO Science Museum",
"price": 1750
},
"type": 1
},
{
"geometry": {
"type": "Point",
"coordinates": [
3429,
3496
]
},
"properties": {
"_id": "3",
"_index": "museums",
"name": "Nederlands Scheepvaartmuseum",
"price": 1650
},
"type": 1
},
{
"geometry": {
"type": "Point",
"coordinates": [
3429,
3496
]
},
"properties": {
"_id": "4",
"_index": "museums",
"name": "Amsterdam Centre for Architecture",
"price": 0
},
"type": 1
}
]
},
"aggs": {
"extent": 4096,
"version": 2,
"features": [
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
3072,
3072
],
[
4096,
3072
],
[
4096,
4096
],
[
3072,
4096
],
[
3072,
3072
]
]
]
},
"properties": {
"_count": 3,
"max_price.value": 1750.0,
"min_price.value": 0.0,
"avg_price.value": 1133.3333333333333
},
"type": 3
}
]
},
"meta": {
"extent": 4096,
"version": 2,
"features": [
{
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
0,
0
],
[
4096,
0
],
[
4096,
4096
],
[
0,
4096
],
[
0,
0
]
]
]
},
"properties": {
"_shards.failed": 0,
"_shards.skipped": 0,
"_shards.successful": 1,
"_shards.total": 1,
"aggregations._count.avg": 3.0,
"aggregations._count.count": 1,
"aggregations._count.max": 3.0,
"aggregations._count.min": 3.0,
"aggregations._count.sum": 3.0,
"aggregations.avg_price.avg": 1133.3333333333333,
"aggregations.avg_price.count": 1,
"aggregations.avg_price.max": 1133.3333333333333,
"aggregations.avg_price.min": 1133.3333333333333,
"aggregations.avg_price.sum": 1133.3333333333333,
"aggregations.max_price.avg": 1750.0,
"aggregations.max_price.count": 1,
"aggregations.max_price.max": 1750.0,
"aggregations.max_price.min": 1750.0,
"aggregations.max_price.sum": 1750.0,
"aggregations.min_price.avg": 0.0,
"aggregations.min_price.count": 1,
"aggregations.min_price.max": 0.0,
"aggregations.min_price.min": 0.0,
"aggregations.min_price.sum": 0.0,
"hits.max_score": 0.0,
"hits.total.relation": "eq",
"hits.total.value": 3,
"timed_out": false,
"took": 2
},
"type": 3
}
]
}
}