Vector Services Index Query Reference Overview

Overview of the Index Query API

These endpoints work in any application.

Index Query API Parameters#

ParameterData TypeParameter TypeDescription
aggsStringQueryThe aggregation definitions (see Aggregations for details).
countIntegerQueryDefinition for index query: The number of records to return per shard per page request. Definition for index aggregation: The number of groupings to return per aggregation, used to display the top N buckets for an aggregation. Default 10.
endDateStringQueryA convenience parameter for setting the value for the latest item_date value to be included in the set of aggregated items. Note: The date range can be specified with ISO-8601 date strings or with expressions using the term "now" to indicate the current date. The date expressions can include simple "date math" by appending "+" or "-" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read "now-1d". The units supported are "y" (year), "M" (month), "w" (week), "d" (day), "h" (hour), "m" (minute), and "s" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included.
fieldsStringPathThe comma-separated list of fields to return for the items. Example: item_date,source,item_type
indexStringPathThe index to which vector items are stored. Note: All indicies follow the format vector-{user defined index name} or vector-web-{geohash}.
leftStringQueryThe leftmost X-coordinate for the bounding box; longitude in decimal degrees of the lower left bounding box corner.
lowerStringQueryThe lowest Y-coordinate for the bounding box; latitude in decimal degrees of the lower left bounding box corner.
pagingIdStringFormThe paging session ID for which to retrieve a page.
qStringQueryThe Elasticsearch query string to constrain the document set.
queryStringQueryThe Elasticsearch query string to filter the source items for the aggregations. See Query Syntax, Fields, and Type Suffixes for more detail.
rightStringQueryThe rightmost X-coordinate for the bounding box; longitude in decimal degrees of the upper right bounding box corner.
shapeStringQueryGeoJSON of the aoi in GeometryCollection format. Example: {"type":"GeometryCollection","geometries":[{"type": "MultiPolygon","coordinates": [[[[-109.0283203125,36.98500309285596],[-109.0283203125,40.97989806962013],[-102.06298828125,40.97989806962013],[-102.06298828125,37.00255267215955],[-109.0283203125,36.98500309285596]]]]}]}
sortStringQueryA convenience parameter for sorting the returned results. Defaults to ascending, but the user has the option of specifying ascending or descending order with asc and desc. Any vector fields may be used in conjunction with sort, and multiple fields may be used at once, separated by a comma. Example: sort=item_type, sort=item_date:desc, sort=ingest_source:asc,attributes.name:desc
spatialRelationStringQueryHow a provided geometry is used to filter results. Requires either bbox geometry or GeoJSON geometry, or is ignored. Defaults to intersects, but the user has the option of specifying intersects (any items that cross or touch the provided geometry in any way), contains (any items that completely cover the provided geometry), within (any items that are completely covered by the provided geometry), or disjoint (any items that do not touch the provided geometry).
startDateStringQueryA convenience parameter for setting the value for the earliest item_date value to be included in the set of aggregated items. Note: The date range can be specified with ISO-8601 date strings or with expressions using the term "now" to indicate the current date. The date expressions can include simple "date math" by appending "+" or "-" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read "now-1d". The units supported are "y" (year), "M" (month), "w" (week), "d" (day), "h" (hour), "m" (minute), and "s" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included.
upperStringQueryThe highest Y-coordinate for the bounding box; latitude in decimal degrees of the upper right bounding box corner.

Index Query Aggregations Type Definitions#

Aggregation QueryDefinition
avgComputes the average of the values for the document field. The field definition is required. For example: To compute the average for the “positive sentiment” attribute value, use “avg:attributes.sentiment_positive_dbl”. Note: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either _int or _dbl.
avg_geo_latComputes the average latitude of the point_samples field for a set of documents.
avg_geo_lonComputes the average longitude of the point_samples field for a set of documents.
cardinalityComputes the number of unique values for the document field specified. The field definition is required. For example: To compute the number of unique values for the ingest_source field, use cardinality:ingest_source.
date_histCounts the set of documents into buckets based on the item_date field. An optional interval may be added to the aggregation definition to change the time unit for each bucket. The units supported are d (day), h (hour), m (minute), s (second), ms (millisecond), micros, nanos, year, quarter, month, week, day, hour, minute, second. Note that any duration value must be an integer, e.g. 1d, and duration values are only used on d, h, m, and s values. For example: To bucket a set of documents by minute, use date_hist:m. The default unit is d (date_hist:d).
geohashCounts the set of documents into buckets based on the geohash of the point_samples field. An optional precision may be added to the aggregation definition to change the length of the geohash for each bucket. For example: To bucket a set of documents by four-character geohashes, use geohash:4. The default precision is six characters (geohash:6).
maxComputes the maximum value for a document field. The field definition is required. For example: To compute the maximum x coordinate value, use "max:max_x". Note: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either _int or _dbl. Fields ending in _date may also be used.
minComputes the minimum value for a document field. The field definition is required. For example: To compute the minimum for the "attributes.cloudCover_int" attribute value, use "min:attributes.cloudCover_int". Note: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either _int or _dbl. Fields ending in _date may also be used.
sumComputes the sum of the values for the document field. The field definition is required. For example: To compute the sum for the "count_int" attribute value of the Car Count vectors, use sum:attributes.count_int. Note: Sum works with numeric attributes - those ending with either _int or _dbl.
termsCounts the set of documents into buckets based on the unique values of the document field specified in the aggregation definition. The field definition is required. For example: To count documents into buckets based on unique terms in the ingest_source field, use terms:ingest_source.

Note: aggregations can be nested within each other by creating a sequence of aggregation definitions separated by semi-colons. A final “grouping” of aggregations can be at the bottom level by surrounding the final set of aggregations with parentheses and separating them by commas. For example, to group a set of documents by geohash, time range, and finally to count the total number of terms in and list the most highly-occurring values for the ingest_source field in those groups, the 'aggs' definition might look like this: geohash:4;date_hist:d;(cardinality:ingest_source,terms:ingest_source) or terms:item_type;(min:min_y, min:min_x, max:max_y, max:max_x)

Note: query aggregations can be made using either a bounding box to reference the aoi, or using polygons for a more precise aoi/multiple aois. For a bounding box, use the GET method with the upper/lower X/Y parameters. For an arbitrary polygon, use the POST method with a GeoJSON-formatted polygon definition in the body of the request.

Index Query Parameter Limits#

ParametersLimits
fieldsPossible field options are: attributes, format, geom, geom_type, id, ingest_attributes, ingest_date, ingest_source, item_date, item_type, name, original_crs, source, text. Note: geom will always display, even if not specified.
leftBetween -180 and 180 degrees inclusive.
lowerBetween -90 and 90 degrees inclusive.
rightBetween -180 and 180 degrees inclusive.
upperBetween -90 and 90 degrees inclusive.

Associated API Calls for Index Query Vector Services#

Index Query: Aggregation by Bounding Box
Index Query: Aggregation by Shape
Index Query: Get Paging ID for Bounding Box
Index Query: Get Paging ID for Shape
Index Query: List Vector Items for Bounding Box (Returns Default Fields)
Index Query: List Vector Items for Bounding Box (Returns Selected Fields)
Index Query: List Vector Items for Shape
Retrieve Page of Vector Items