REST Pub API: EventTemplateSearch facets
The EventTemplateSearch resource supports the generation of facets that can be included in the result payload for HTTP GET requests.
Facets are generated by aggregating the different values of specific attributes/fields and generating buckets with counts for each value found. Facets are highly useful for creating navigation and dropdown lists that let users select from known values to filter results further. Facets generally eliminate the need to manually loop over results count distinct values of fields.
For example, to produce a list of distinct categories with a count of their templates, a facet on the Category field can be used. The facet buckets (each representing a distinct category) could be converted to a dropdown list, and website visitors could use this list to click on a category and have the list appropriately filtered to show only templates from that category.
By default, facets are generated on an unfiltered result set, even if a general
filter query parameter has been specified—this filter applies only to the
Items results, and is not used by facets. To produce facets on a filtered set of results, you must use the
facetsfilter parameter which follows the same filter rules.
Facet information is returned in response to facet requests encoded in the
facets query parameter. Multiple requests can be included in this query parameter, and each will have a corresponding facet response in the HTTP response payload. Requests can be specified in two formats: simple and advanced.
The simple format is a simple comma-separated list of facet codes (see specification for available codes). Default settings will be used when generating each facet.
- Request one facet:
- Request multiple facets:
The advanced format allows you to control how many facet values (or buckets) are returned, and the sort order of the buckets. Additional parameters for a facet are included in brackets after the facet code in the format:
facet_code: The code of the facet (see specification for available codes).
top(optional): Return only the top n facets (where a full list of distinct values is not needed), use the
toprequest parameter. The value n must be a positive integer. Default is to return all facet values.
orderby(optional): Order facet values based on their
countin descending order (with highest counts first), or by their
labelvalue (alphabetical sort). Default is to sort facet values by
- Request one facet:
- Request two facets:
This section provides a list of codes that can be used as part of a facet request.
|Generates value buckets based on distinct category values.
|Generates value buckets based on distinct presenter values.
|Generates value buckets based on distinct tags..
Facet requests result in a response included in the HTTP response payload under the
Facets field is an array of facet Responses (one corresponding to each facet request) representing the results from an analysis of a particular event attribute. Each response entry has a number of fields that describe the results.
|Describes the name of the facet or attribute.
|The code of the facet (same as that used in the original request)
The code of the associated filter that can be used to produce a list of
actual events for each Value. Use of the
FilterCode is common in drill-down scenarios where a user wants to construct a followup API call to see the actual list of events filtered by a particular value of a facet.
The total count of distinct values found for the facet, independent of the number included in the actual payload (if
top has been specified in the facet request to limit the number of returned results).
An array of Bucket structures representing distinct values found for the facet. Each entry represents a unique value with the count of events that have that value.
The Bucket structure has a number of fields: