Search a vector tile | Elasticsearch API documentation

Path parameters

indexstring | array[string] Required
Comma-separated list of data streams, indices, or aliases to search
fieldstring Required
Field containing geospatial data to return
zoomnumber Required
Zoom level for the vector tile to search
xnumber Required
X coordinate for the vector tile to search
ynumber Required
Y coordinate for the vector tile to search

Query parameters

exact_boundsboolean
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.
extentnumber
The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
grid_aggstring
Aggregation used to create a grid for field.
Values are geotile or geohex.
grid_precisionnumber
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_typestring
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.
sizenumber
Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
with_labelsboolean
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.
- 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.

application/json

Body

aggsobject
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.
buffernumber
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_boundsboolean
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.
extentnumber
The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
fieldsstring | array[string]
grid_aggstring
Values are geotile or geohex.
grid_precisionnumber
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.
grid_typestring
Values are grid, point, or centroid.
queryobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
runtime_mappingsobject
Hide runtime_mappings attribute Show runtime_mappings attribute object
- *object Additional properties
  Hide * attributes Show * attributes object
  fieldsobject
  For type composite
  Hide fields attribute Show fields attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  fetch_fieldsarray[object]
  For type lookup
  Hide fetch_fields attributes Show fetch_fields attributes object
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  formatstring
  formatstring
  A custom format for date type runtime fields.
  input_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_indexstring
  scriptobject
  Hide script attributes Show script attributes object
  sourcestring | object
  One of:
  ScriptSourcestring SearchRequestBodyobject
  Hide attributes Show attributes
  aggregationsobject
  Defines the aggregations that are run as part of the search request.
  External documentation
  collapseobject
  External documentation
  explainboolean
  If true, the request returns detailed information about score computation as part of a hit.
  extobject
  Configuration of search extensions defined by Elasticsearch plugins.
  Hide ext attribute Show ext attribute object
  *object Additional properties
  fromnumber
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  highlightobject
  track_total_hitsboolean | 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.
  indices_boostarray[object]
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  External documentation
  docvalue_fieldsarray[object]
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  A reference to a field with formatting instructions on how to return the value
  External documentation
  A reference to a field with formatting instructions on how to return the value
  knnobject | array[object]
  The approximate kNN search to run.
  One of:
  KnnSearchobject array-2array[object]
  rankobject
  Hide rank attribute Show rank attribute object
  rrf
  min_scorenumber
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  post_filterobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  profileboolean
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  queryobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  rescorearray[object]
  retrieverobject
  Hide retriever attributes Show retriever attributes object
  standard
  knn
  rrf
  text_similarity_reranker
  rule
  rescorer
  linear
  pinned
  script_fieldsobject
  Retrieve a script evaluation (based on different fields) for each hit.
  Hide script_fields attribute Show script_fields attribute object
  *object Additional properties
  search_afterarray[number | string | boolean | null]
  A field value.
  sizenumber
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  sliceobject
  Hide slice attributes Show slice attributes object
  fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  idstring Required
  maxnumber Required
  sortarray[string | object]
  _sourceboolean | object
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  One of:
  SourceConfigboolean SourceFilterobject
  fieldsarray[object]
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  A reference to a field with formatting instructions on how to return the value
  A reference to a field with formatting instructions on how to return the value
  suggestobject
  Hide suggest attribute Show suggest attribute object
  textstring
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  terminate_afternumber
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  If set to 0 (default), the query does not terminate early.
  timeoutstring
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  track_scoresboolean
  If true, calculate and return document scores, even if the scores are not used for sorting.
  versionboolean
  If true, the request returns the document version as part of a hit.
  seq_no_primary_termboolean
  If true, the request returns sequence number and primary term of the last modification of each hit.
  External documentation
  stored_fieldsstring | array[string]
  pitobject
  Hide pit attributes Show pit attributes object
  idstring Required
  keep_alivestring
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  runtime_mappingsobject
  statsarray[string]
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  idstring
  paramsobject
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  Hide params attribute Show params attribute object
  *object Additional properties
  langstring
  Any of:
  ScriptLanguagestring ScriptLanguagestring
  Values are painless, expression, mustache, or java.
  optionsobject
  Hide options attribute Show options attribute object
  *string Additional properties
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
sizenumber
The maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
sortstring | object | array[string | object]
One of:
Fieldstring SortOptionsobject Sortarray[string | object]
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes
_scoreobject
Hide _score attribute Show _score attribute object
orderstring
Values are asc or desc.
_docobject
Hide _doc attribute Show _doc attribute object
orderstring
Values are asc or desc.
_geo_distanceobject
Hide _geo_distance attributes Show _geo_distance attributes object
modestring
Values are min, max, sum, avg, or median.
distance_typestring
Values are arc or plane.
ignore_unmappedboolean
orderstring
Values are asc or desc.
unitstring
Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_scriptobject
Hide _script attributes Show _script attributes object
orderstring
Values are asc or desc.
scriptobject Required
Hide script attributes Show script attributes object
sourcestring | object
One of:
ScriptSourcestring SearchRequestBodyobject
idstring
paramsobject
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
Hide params attribute Show params attribute object
*object Additional properties
langstring
Any of:
ScriptLanguagestring ScriptLanguagestring
Values are painless, expression, mustache, or java.
optionsobject
Hide options attribute Show options attribute object
*string Additional properties
typestring
Values are string, number, or version.
modestring
Values are min, max, sum, avg, or median.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Fieldstring SortOptionsobject
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes
_scoreobject
Hide _score attribute Show _score attribute object
orderstring
Values are asc or desc.
_docobject
Hide _doc attribute Show _doc attribute object
orderstring
Values are asc or desc.
_geo_distanceobject
Hide _geo_distance attributes Show _geo_distance attributes object
modestring
Values are min, max, sum, avg, or median.
distance_typestring
Values are arc or plane.
ignore_unmappedboolean
orderstring
Values are asc or desc.
unitstring
Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_scriptobject
Hide _script attributes Show _script attributes object
orderstring
Values are asc or desc.
scriptobject Required
Hide script attributes Show script attributes object
source
idstring
paramsobject
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
lang
optionsobject
typestring
Values are string, number, or version.
modestring
Values are min, max, sum, avg, or median.
nestedobject
Hide nested attributes Show nested attributes object
filterobject
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
max_childrennumber
nestedobject
pathstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
track_total_hitsboolean | 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_labelsboolean
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.
- 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.

Responses

200 application/json

GET /{index}/_mvt/{field}/{zoom}/{x}/{y}

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"

Request example

Run `GET museums/_mvt/location/13/4207/2692` to search an index for `location` values that intersect the `13/4207/2692` vector tile.

{
  "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 examples (200)

A successful response from `GET museums/_mvt/location/13/4207/2692`. It 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
      }
    ]
  }
}

Path parameters

Query parameters

Body

sourcestring | object

langstring

sortstring | object | array[string | object]

sourcestring | object

langstring

Responses