All methods and paths for this operation:
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:
geo_bounding_box query on the <field>. The query uses the <zoom>/<x>/<y> tile as a bounding box.geotile_grid or geohex_grid aggregation on the <field>. The grid_agg parameter determines the aggregation type. The aggregation uses the <zoom>/<x>/<y> tile as a bounding box.geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition 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.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:
hits layer containing a feature for each <field> value matching the geo_bounding_box query.aggs layer containing a feature for each cell of the geotile_grid or geohex_grid. The layer only contains features for cells with matching data.geotile_grid or geohex_grid.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.
Learn how to use the vector tile search API with practical examples in the Vector tile search examples guide.
readComma-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
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.
The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
Aggregation used to create a grid for field.
Values are geotile or geohex.
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.
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, or centroid.
Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
The 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.
If true, the hits and aggs layers will contain additional point features representing
suggested label positions for the original features.
Point and MultiPoint features will have one of the points selected.Polygon and MultiPolygon 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.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.
Sub-aggregations for the geotile_grid.
It supports the following aggregation types:
avgboxplotcardinalityextended statsmaxmedian absolute deviationminpercentilepercentile-rankstatssumvalue countThe aggregation names can't start with _mvt_. The _mvt_ prefix is reserved for internal aggregations.
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.
Default value is 5.
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 <zoom>/<x>/<y> tile with wrap_longitude set to false. The resulting
bounding box may be larger than the vector tile.
Default value is false.
The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
Default value is 4096.
The fields to return in the hits layer.
It supports wildcards (*).
This parameter does not support fields with array values. Fields with array
values may return inconsistent results.
The aggregation used to create a grid for the field.
Values are geotile or geohex.
Additional zoom levels available through the aggs layer. For example, if <zoom> 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.
Default value is 8.
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. Ifpoint`, each feature is a Point that is the centroid
of the cell.
Values are grid, point, or centroid.
The query DSL used to filter documents for the search.
Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.
The maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
Default value is 10000.
Sort the features in the hits layer. By default, the API calculates a bounding box for each feature. It sorts features based on this box's diagonal length, from longest to shortest.
Sort the features in the hits layer. By default, the API calculates a bounding box for each feature. It sorts features based on this box's diagonal length, from longest to shortest.
Sort the features in the hits layer. By default, the API calculates a bounding box for each feature. It sorts features based on this box's diagonal length, from longest to shortest.
The 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.
If true, the hits and aggs layers will contain additional point features representing
suggested label positions for the original features.
Point and MultiPoint features will have one of the points selected.Polygon and MultiPolygon 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.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.
GET museums/_mvt/location/13/4207/2692
{
"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"
}
}
}
}resp = client.search_mvt(
index="museums",
field="location",
zoom="13",
x="4207",
y="2692",
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"
}
}
},
)const response = await client.searchMvt({
index: "museums",
field: "location",
zoom: 13,
x: 4207,
y: 2692,
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",
},
},
},
});response = client.search_mvt(
index: "museums",
field: "location",
zoom: "13",
x: "4207",
y: "2692",
body: {
"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"
}
}
}
}
)$resp = $client->searchMvt([
"index" => "museums",
"field" => "location",
"zoom" => "13",
"x" => "4207",
"y" => "2692",
"body" => [
"grid_agg" => "geotile",
"grid_precision" => 2,
"fields" => array(
"name",
"price",
),
"query" => [
"term" => [
"included" => true,
],
],
"aggs" => [
"min_price" => [
"min" => [
"field" => "price",
],
],
"max_price" => [
"max" => [
"field" => "price",
],
],
"avg_price" => [
"avg" => [
"field" => "price",
],
],
],
],
]);curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"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"}}}}' "$ELASTICSEARCH_URL/museums/_mvt/location/13/4207/2692"{
"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
}
]
}
}