Vector tile search API
editVector tile search API
editSearches a vector tile for geospatial values. Returns results as a binary Mapbox vector tile.
GET my-index/_mvt/my-geo-field/15/5271/12710
Prerequisites
edit- Before using this API, you should be familiar with the Mapbox vector tile specification.
-
If the Elasticsearch security features are enabled, you must have the
read
index privilege for the target data stream, index, or alias. For cross-cluster search, see Cross-cluster search and security.
Path parameters
edit-
<target>
-
(Required, string) Comma-separated list of data streams, indices, or aliases to search. Supports wildcards (
*
). To search all data streams and indices, omit this parameter or use*
or_all
.To search a remote cluster, use the
<cluster>:<target>
syntax. See Search across clusters. -
<field>
-
(Required, string) Field containing geospatial values to return. Must be a
geo_point
orgeo_shape
field. The field must have doc values enabled. Cannot be a nested field.Vector tiles do not natively support geometry collections. For
geometrycollection
values in ageo_shape
field, the API returns ahits
layer feature for each element of the collection. This behavior may change may change in a future release. -
<zoom>
-
(Required, integer) Zoom level for the vector tile to search. Accepts
0
-29
. -
<x>
- (Required, integer) X coordinate for the vector tile to search.
-
<y>
- (Required, integer) Y coordinate for the vector tile to search.
Description
editInternally, 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
aggregation on the<field>
. 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
.
For example, Elasticsearch may translate a vector tile search API request with 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
. You can use these cells as tiles for lower zoom levels. 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
. - 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.
Query parameters
editYou 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.
-
exact_bounds
-
(Optional, Boolean) If
false
, themeta
layer’s feature is the bounding box of the tile. Defaults tofalse
.If
true
, themeta
layer’s feature is a bounding box resulting from ageo_bounds
aggregation. The aggregation runs on<field>
values that intersect the<zoom>/<x>/<y>
tile withwrap_longitude
set tofalse
. The resulting bounding box may be larger than the vector tile.
-
extent
-
(Optional, integer) Size, in pixels, of a side of the tile. Vector tiles are
square with equal sides. Defaults to
4096
.
-
grid_precision
-
(Optional, integer) Additional zoom levels available through the
aggs
layer. For example, if<zoom>
is7
andgrid_precision
is8
, you can zoom in up to level 15. Accepts0
-8
. Defaults to8
. If0
, results don’t include theaggs
layer.This value determines the grid size of the
geotile_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. Theaggs
layer only contains features for cells with matching data.
-
grid_type
-
(Optional, string) Determines the geometry type for features in the
aggs
layer. In theaggs
layer, each feature represents ageotile_grid
cell. Accepts:-
grid
(Default) -
Each feature is a
Polygon
of the cell’s bounding box. -
point
-
Each feature is a
Point
that’s the centroid of the cell. -
centroid
-
Each feature is a
Point
that’s the centroid of the data within the cell. For complex geometries, the actual centroid may be outside the cell. In these cases, the feature is set to the closest point to the centroid inside the cell.
-
-
size
-
(Optional, integer) Maximum number of features to return in the
hits
layer. Accepts0
-10000
. Defaults to10000
. If0
, results don’t include thehits
layer.
-
track_total_hits
-
(Optional, integer or Boolean) Number of hits matching the query to count accurately. Defaults to
10000
.If
true
, the exact number of hits is returned at the cost of some performance. Iffalse
, the response does not include the total number of hits matching the query.
Request body
edit-
aggs
-
(Optional, aggregation object) Sub-aggregations for the
geotile_grid
. Supports the following aggregation types:-
avg
-
boxplot
-
cardinality
-
extended stats
-
max
-
median absolute deviation
-
min
-
percentile
-
percentile-rank
-
stats
-
sum
-
The aggregation names can’t start with
_mvt_
. The_mvt_
prefix is reserved for internal aggregations.
-
-
exact_bounds
-
(Optional, Boolean) If
false
, themeta
layer’s feature is the bounding box of the tile. Defaults tofalse
.If
true
, themeta
layer’s feature is a bounding box resulting from ageo_bounds
aggregation. The aggregation runs on<field>
values that intersect the<zoom>/<x>/<y>
tile withwrap_longitude
set tofalse
. The resulting bounding box may be larger than the vector tile. -
extent
-
(Optional, integer) Size, in pixels, of a side of the tile. Vector tiles are
square with equal sides. Defaults to
4096
. -
fields
-
(Optional, array of strings and objects) Fields to return in the
hits
layer. Supports wildcards (*
).This parameter does not support fields with array values. Fields with array values may return inconsistent results.
You can specify fields in the array as a string or object.
Properties of
fields
objects-
field
-
(Required, string) Field to return. Supports wildcards (
*
). -
format
-
(Optional, string) Format for date and geospatial fields. Other field data types do not support this parameter.
date
anddate_nanos
fields accept a date format.geo_point
andgeo_shape
fields accept:-
geojson
(default) - GeoJSON
-
wkt
- Well Known Text
-
mvt(<zoom>/<x>/<y>@<extent>)
ormvt(<zoom>/<x>/<y>)
-
Binary Mapbox vector tile. The API returns the tile as a base64-encoded string.
mvt
parameters-
<zoom>
-
(Required, integer) Zoom level for the tile. Accepts
0
-29
. -
<x>
- (Required, integer) X coordinate for the tile.
-
<y>
- (Required, integer) Y coordinate for the tile.
-
<extent>
-
(Optional, integer) Size, in pixels, of a side of the tile. Vector tiles are
square with equal sides. Defaults to
4096
.
-
-
-
-
grid_precision
-
(Optional, integer) Additional zoom levels available through the
aggs
layer. For example, if<zoom>
is7
andgrid_precision
is8
, you can zoom in up to level 15. Accepts0
-8
. Defaults to8
. If0
, results don’t include theaggs
layer.This value determines the grid size of the
geotile_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. Theaggs
layer only contains features for cells with matching data. -
grid_type
-
(Optional, string) Determines the geometry type for features in the
aggs
layer. In theaggs
layer, each feature represents ageotile_grid
cell. Accepts:-
grid
(Default) -
Each feature is a
Polygon
of the cell’s bounding box. -
point
-
Each feature is a
Point
that’s the centroid of the cell. -
centroid
-
Each feature is a
Point
that’s the centroid of the data within the cell. For complex geometries, the actual centroid may be outside the cell. In these cases, the feature is set to the closest point to the centroid inside the cell.
-
-
query
- (Optional, object) Query DSL used to filter documents for the search.
-
runtime_mappings
-
(Optional, object of objects) Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.
Properties of
runtime_mappings
objects-
<field-name>
-
(Required, object) Configuration for the runtime field. The key is the field name.
Properties of
<field-name>
-
type
-
(Required, string) Field type, which can be any of the following:
-
boolean
-
composite
-
date
-
double
-
geo_point
-
ip
-
keyword
-
long
-
-
script
-
(Optional, string) Painless script executed at query time. The script has access to the entire context of a document, including the original
_source
and any mapped fields plus their values.This script must include
emit
to return calculated values. For example:"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"
-
-
-
size
-
(Optional, integer) Maximum number of features to return in the
hits
layer. Accepts0
-10000
. Defaults to10000
. If0
, results don’t include thehits
layer. -
sort
-
(Optional, array of sort objects) Sorts 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.
-
track_total_hits
-
(Optional, integer or Boolean) Number of hits matching the query to count accurately. Defaults to
10000
.If
true
, the exact number of hits is returned at the cost of some performance. Iffalse
, the response does not include the total number of hits matching the query.
Response
editReturned vector tiles contain the following data:
-
hits
-
(object) Layer containing results for the
geo_bounding_box
query.Properties of
hits
-
extent
- (integer) Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
version
- (integer) Major version number of the Mapbox vector tile specification.
-
features
-
(array of objects) Array of features. Contains a feature for each
<field>
value that matches thegeo_bounding_box
query.Properties of
features
objects-
geometry
-
(object) Geometry for the feature.
Properties of
geometry
-
type
-
(string) Geometry type for the feature. Valid values are:
-
UNKNOWN
-
POINT
-
LINESTRING
-
POLYGON
-
-
coordinates
- (array of integers or array of arrays) Tile coordinates for the feature.
-
-
properties
-
(object) Properties for the feature.
Properties of
properties
-
_id
-
(string) Document
_id
for the feature’s document. -
_index
- (string) Name of the index for the feature’s document.
-
<field>
-
Field value. Only returned for fields in the
fields
parameter.
-
-
type
-
(integer) Identifier for the feature’s geometry type. Values are:
-
1
(POINT
) -
2
(LINESTRING
) -
3
(POLYGON
)
-
-
-
-
aggs
-
(object) Layer containing results for the
geotile_grid
aggregation and its sub-aggregations.Properties of
aggs
-
extent
- (integer) Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
version
- (integer) Major version number of the Mapbox vector tile specification.
-
features
-
(array of objects) Array of features. Contains a feature for each cell of the
geotile_grid
.Properties of
features
objects-
geometry
-
(object) Geometry for the feature.
Properties of
geometry
-
type
-
(string) Geometry type for the feature. Valid values are:
-
UNKNOWN
-
POINT
-
LINESTRING
-
POLYGON
-
-
coordinates
- (array of integers or array of arrays) Tile coordinates for the feature.
-
-
properties
-
(object) Properties for the feature.
Properties of
properties
-
_count
- (long) Count of the cell’s documents.
-
_key
-
(string) Bucket key of the cell in the format
<zoom>/<x>/<y>
. -
<sub-aggregation>.value
-
Sub-aggregation results for the cell. Only returned for sub-aggregations in the
aggs
parameter.
-
-
type
-
(integer) Identifier for the feature’s geometry type. Values are:
-
1
(POINT
) -
2
(LINESTRING
) -
3
(POLYGON
)
-
-
-
-
meta
-
(object) Layer containing metadata for the request.
Properties of
meta
-
extent
- (integer) Size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
-
version
- (integer) Major version number of the Mapbox vector tile specification.
-
features
-
(array of objects) Contains a feature for a bounding box.
Properties of
features
objects-
geometry
-
(object) Geometry for the feature.
Properties of
geometry
-
type
-
(string) Geometry type for the feature. Valid values are:
-
UNKNOWN
-
POINT
-
LINESTRING
-
POLYGON
-
-
coordinates
- (array of integers or array of arrays) Tile coordinates for the feature.
-
-
properties
-
(object) Properties for the feature.
Properties of
properties
-
_shards.failed
-
(integer) Number of shards that failed to execute the search. See the search
API’s
shards
response property. -
_shards.skipped
-
(integer) Number of shards that skipped the search. See the search
API’s
shards
response property. -
_shards.successful
-
(integer) Number of shards that executed the search successfully. See the
search API’s
shards
response property. -
_shards.total
-
(integer) Total number of shards that required querying, including unallocated
shards. See the search API’s
shards
response property. -
aggregations._count.avg
-
(float) Average
_count
value for features in theaggs
layer. -
aggregations._count.count
-
(integer) Number of unique
_count
values for features in theaggs
layer. -
aggregations._count.max
-
(float) Largest
_count
value for features in theaggs
layer. -
aggregations._count.min
-
(float) Smallest
_count
value for features in theaggs
layer. -
aggregations._count.sum
-
(float) Sum of
_count
values for features in theaggs
layer. -
aggregations.<sub-aggregation>.avg
- (float) Average value for the sub-aggregation’s results.
-
aggregations.<agg_name>.count
- (integer) Number of unique values from the sub-aggregation’s results.
-
aggregations.<agg_name>.max
- (float) Largest value from the sub-aggregation’s results.
-
aggregations.<agg_name>.min
- (float) Smallest value from the sub-aggregation’s results.
-
aggregations.<agg_name>.sum
- (float) Sum of values for the sub-aggregation’s results.
-
hits.max_score
-
(float) Highest document
_score
for the search’s hits. -
hits.total.relation
-
(string) Indicates whether
hits.total.value
is accurate or a lower bound. Possible values are:-
eq
- Accurate
-
gte
- Lower bound
-
-
hits.total.value
- (integer) Total number of hits for the search.
-
timed_out
-
(Boolean) If
true
, the search timed out before completion. Results may be partial or empty. -
took
-
(integer) Milliseconds it took Elasticsearch to run the search. See the search API’s
took
response property.
-
-
type
-
(integer) Identifier for the feature’s geometry type. Values are:
-
1
(POINT
) -
2
(LINESTRING
) -
3
(POLYGON
)
-
-
-
Examples
editThe following requests create the museum
index and add several geospatial
location
values.
PUT museums { "mappings": { "properties": { "location": { "type": "geo_point" }, "name": { "type": "keyword" }, "price": { "type": "long" }, "included": { "type": "boolean" } } } } POST museums/_bulk?refresh { "index": { "_id": "1" } } { "location": "52.374081,4.912350", "name": "NEMO Science Museum", "price": 1750, "included": true } { "index": { "_id": "2" } } { "location": "52.369219,4.901618", "name": "Museum Het Rembrandthuis", "price": 1500, "included": false } { "index": { "_id": "3" } } { "location": "52.371667,4.914722", "name": "Nederlands Scheepvaartmuseum", "price":1650, "included": true } { "index": { "_id": "4" } } { "location": "52.371667,4.914722", "name": "Amsterdam Centre for Architecture", "price":0, "included": true }
The following request searches the index for location
values that intersect
the 13/4207/2692
vector tile.
GET museums/_mvt/location/13/4207/2692 { "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" } } } }
The API returns results as a binary vector tile. When decoded into JSON, the tile contains the following data:
{ "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 } ] } }