{"_id":"56e1cdd892bf640e00b5564b","category":{"_id":"56e1ccc4e416450e00b9e48c","project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","pages":["56e1cdd892bf640e00b5564b","56e1cdfde416450e00b9e490","56e1ce4892bf640e00b5564e","56e1ce81e416450e00b9e494","56e1ceebe416450e00b9e497","56e1cf39cd6a8d0e00d12176","56e30b4b51857d0e008e77a3","56e30bd26e602e0e00700b16","56e30dd0d46bc30e007bb986","56e30e3d872bb20e0051ba39","56e30f91cb6ef20e0084f23c"],"__v":11,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-10T19:36:36.026Z","from_sync":false,"order":17,"slug":"aggregations-facets-vector-services-guide","title":"Aggregations & Facets Vector Services Guide"},"__v":6,"project":"55faeacad0e22017005b8265","parentDoc":null,"user":"56267741db1eda0d001c3dbb","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":35,"createdAt":"2015-09-17T16:31:06.800Z","releaseDate":"2015-09-17T16:31:06.800Z","categories":["55faeacbd0e22017005b8269","55faf550764f50210095078e","55faf5b5626c341700fd9e96","55faf8a7825d5f19001fa386","560052f91503430d007cc88f","560054f73aa0520d00da0b1a","56005aaf6932a00d00ba7c62","56005c273aa0520d00da0b3f","5601ae7681a9670d006d164d","5601ae926811d00d00ceb487","5601aeb064866b1900f4768d","5601aee850ee460d0002224c","5601afa02499c119000faf19","5601afd381a9670d006d1652","561d4c78281aec0d00eb27b6","561d588d8ca8b90d00210219","563a5f934cc3621900ac278c","5665c5763889610d0008a29e","566710a36819320d000c2e93","56ddf6df8a5ae10e008e3926","56e1c96b2506700e00de6e83","56e1ccc4e416450e00b9e48c","56e1ccdfe63f910e00e59870","56e1cd10bc46be0e002af26a","56e1cd21e416450e00b9e48e","56e3139a51857d0e008e77be","573b4f62ef164e2900a2b881","57c9d1335fd8ca0e006308ed","57e2bd9d1e7b7220000d7fa5","57f2b992ac30911900c7c2b6","58adb5c275df0f1b001ed59b","58c81b5c6dc7140f003c3c46","595412446ed4d9001b3e7b37","59e76ce41938310028037295","5a009de510890d001c2aabfe"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-10T19:41:12.595Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"| Table of Contents |\n| --- |\n| [Aggregations Vector Services API Parameters](#section-api-parameters) |\n| [Aggregations Vector Services Type Definitions](#section-aggregations-type-definitions) |\n| [Associated API Calls for Aggregations Vector Services](#section-associated-api-calls-for-aggregations-vector-services) |\n\nThese endpoints work in any application.\n\n#API Parameters#\n| Parameter | Data Type | Parameter Type | Description | Required? |\n| --- | --- | --- | --- | --- |\n| aggs | String | Query | The aggregation definitions (see below for more detail). | Required |\n| count  | Integer | Query | The number of groupings to return per aggregation, used to display the top N buckets for an aggregation. Default 10. | Optional |\n| endDate | String | Query | A 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. | Optional; required with `startDate` |\n| left | String | Query | The leftmost X-coordinate for the bounding box; longitude in decimal degrees of the lower left bounding box corner. | Required for bounding box aggregations |\n| lower | String | Query | The lowest Y-coordinate for the bounding box; latitude in decimal degrees of the lower left bounding box corner. | Required for bounding box aggregations |\n| query | String | Query | The Elasticsearch query string to filter the source items for the aggregations.  See [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) for more detail. | Optional |\n| right | String | Query | The rightmost X-coordinate for the bounding box; longitude in decimal degrees of the upper right bounding box corner. | Required for bounding box aggregations |\n| shape | String | Query | GeoJSON 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]]]]}]}``` | Required for shape aggregations |\n| startDate | String | Query | A 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. | Optional; required with `endDate` |\n| upper | String | Query | The highest Y-coordinate for the bounding box; latitude in decimal degrees of the upper right bounding box corner. | Required for bounding box aggregations |\n\n#Aggregations Type Definitions#\n| Aggregation Query | Definition |\n| --- | --- |\n| avg | Computes 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`. |\n| avg_geo_lat | Computes the average latitude of the point_samples field for a set of documents. |\n| avg_geo_lon | Computes the average longitude of the point_samples field for a set of documents. |\n| cardinality | Computes 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`. |\n| date_hist | Counts 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 “y” (year), “M” (month), “w” (week), “d” (day), “h” (hour), “m”  (minute), and “s” (second). For example: To bucket a set of documents by minute, use `date_hist:m`. The default unit is “d” (`date_hist:d`). |\n| geohash | Counts 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`). |\n| sum | Computes 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`. |\n| terms | Counts 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`. |\n\n**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)```\n\n**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 arbitary polygon, use the POST method with a GeoJSON-formatted polygon definition in the body of the request.\n\n**For more information** on querying and query construction, check the [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) page and [Aggregation Example Query Constructions](doc:vector-services-example-query-constructions) page.\n\n#Associated API Calls for Aggregations Vector Services#\n[Query](doc:aggs-query)\n[Shape Query](doc:aggs-shape-query)","excerpt":"Overview of the Aggregations API.","slug":"vector-services-aggregations-reference-overview","type":"basic","title":"Vector Services Aggregations Reference Overview"}

Vector Services Aggregations Reference Overview

Overview of the Aggregations API.

| Table of Contents | | --- | | [Aggregations Vector Services API Parameters](#section-api-parameters) | | [Aggregations Vector Services Type Definitions](#section-aggregations-type-definitions) | | [Associated API Calls for Aggregations Vector Services](#section-associated-api-calls-for-aggregations-vector-services) | These endpoints work in any application. #API Parameters# | Parameter | Data Type | Parameter Type | Description | Required? | | --- | --- | --- | --- | --- | | aggs | String | Query | The aggregation definitions (see below for more detail). | Required | | count | Integer | Query | The number of groupings to return per aggregation, used to display the top N buckets for an aggregation. Default 10. | Optional | | endDate | String | Query | A 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. | Optional; required with `startDate` | | left | String | Query | The leftmost X-coordinate for the bounding box; longitude in decimal degrees of the lower left bounding box corner. | Required for bounding box aggregations | | lower | String | Query | The lowest Y-coordinate for the bounding box; latitude in decimal degrees of the lower left bounding box corner. | Required for bounding box aggregations | | query | String | Query | The Elasticsearch query string to filter the source items for the aggregations. See [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) for more detail. | Optional | | right | String | Query | The rightmost X-coordinate for the bounding box; longitude in decimal degrees of the upper right bounding box corner. | Required for bounding box aggregations | | shape | String | Query | GeoJSON 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]]]]}]}``` | Required for shape aggregations | | startDate | String | Query | A 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. | Optional; required with `endDate` | | upper | String | Query | The highest Y-coordinate for the bounding box; latitude in decimal degrees of the upper right bounding box corner. | Required for bounding box aggregations | #Aggregations Type Definitions# | Aggregation Query | Definition | | --- | --- | | avg | Computes 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_lat | Computes the average latitude of the point_samples field for a set of documents. | | avg_geo_lon | Computes the average longitude of the point_samples field for a set of documents. | | cardinality | Computes 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_hist | Counts 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 “y” (year), “M” (month), “w” (week), “d” (day), “h” (hour), “m” (minute), and “s” (second). For example: To bucket a set of documents by minute, use `date_hist:m`. The default unit is “d” (`date_hist:d`). | | geohash | Counts 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`). | | sum | Computes 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`. | | terms | Counts 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)``` **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 arbitary polygon, use the POST method with a GeoJSON-formatted polygon definition in the body of the request. **For more information** on querying and query construction, check the [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) page and [Aggregation Example Query Constructions](doc:vector-services-example-query-constructions) page. #Associated API Calls for Aggregations Vector Services# [Query](doc:aggs-query) [Shape Query](doc:aggs-shape-query)