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 requests

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.

Simple format

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.

Examples

• Request one facet: ?facets=category
• Request multiple facets: ?facets=category,advertisedpresenter

Advanced format

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:

?facets=facet_code(top=n,orderby=count|label)

Where:

• 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 top request parameter. The value n must be a positive integer. Default is to return all facet values.
• orderby (optional): Order facet values based on their count in descending order (with highest counts first), or by their label value (alphabetical sort). Default is to sort facet values by label.

Examples

• Request one facet: ?facets=category(top=10,orderby=count)
• Request two facets: ?facets=advertisedpresenter(top=10,orderby=count),tag(top=10)

Facets specification

This section provides a list of codes that can be used as part of a facet request.

Facet code	Description
category	Generates value buckets based on distinct category values.
advertisedpresenter	Generates value buckets based on distinct presenter values.
tag	Generates value buckets based on distinct tags..

Facets response

Facet requests result in a response included in the HTTP response payload under the Facets field.

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.

Fields

Field	Description
Name	Describes the name of the facet or attribute.
Code	The code of the facet (same as that used in the original request)
FilterCode	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.
ValuesCount	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).
Values	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: Structure fields Label: A display string for the value. Code: A code that can be used in conjunction with the facet's FilterCode to drill down and produce a list of actual events that have this facet's value. Count: A count of events that have this facet's value.