REST Pub API: EventSearch facets
The EventSearch 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 (see example screenshot) 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 events, 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 events from that category. To produce a list of venue states with a count of events in each, a facet on the State field can be used, and visitors could then filter a list of events to show only those running near where they live.
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.
General structure
Example facet response for State (event venue state) showing the different value buckets and the count of events for each.
{
"Facets":[
{
"Name":"State",
"Code":"state",
"FilterCode":"statecode",
"ValuesCount":5,
"Values":[
{
"Label":"NSW",
"Code":"NSW",
"Count":28
},
{
"Label":"VIC",
"Code":"VIC",
"Count":13
},
{
"Label":"WA",
"Code":"WA",
"Count":9
},
{
"Label":"QLD",
"Code":"QLD",
"Count":8
},
{
"Label":"NT",
"Code":"NT",
"Count":2
}
]
}
],
"StartIndex":0,
"Count":20,
"Items":[
...
]
}
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=locname - Request multiple facets:
?facets=locname,presenter
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 thetoprequest parameter. The value n must be a positive integer. Default is to return all facet values.orderby(optional): Order facet values based on theircountin descending order (with highest counts first), or by theirlabelvalue (alphabetical sort). Default is to sort facet values bylabel.
Examples
- Request one facet:
?facets=locname(top=10,orderby=count) - Request two facets:
?facets=locname(top=10,orderby=count),presenter(top=10)
Facets specification
This section provides a list of codes that can be used as part of a facet request.
| Facet code | Description |
|---|---|
| locname | Generates value buckets based on distinct event location name string values. |
| city | Generates value buckets based on distinct event city string values. |
| citysuburb | Generates value buckets based on distinct event city and suburb value pairs. |
| state | Generates value buckets based on distinct event state string values. |
| venue | Generates value buckets based on distinct venues hosting events. |
| template | Generates value buckets based on distinct event templates. |
| templatecategory | Generates value buckets based on distinct categories used by event templates. |
| tag | Generates value buckets based on distinct event tag values. |
| templatetag | Generates value buckets based on distinct event template tag values. |
| presenter | Generates value buckets based on distinct event presenters. |
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
|
Example response for a request of the templatecategory facet (relevant payload part):
{
"Facets":[
{
"Name":"Category",
"Code":"templatecategory",
"FilterCode":"templatecategoryid",
"ValuesCount":2,
"Values":[
{
"Label":"Sales & Marketing",
"Code":"9035",
"Count":16
},
{
"Label":"Leadership",
"Code":"9032",
"Count":11
}
]
}
],
"StartIndex":0,
"Count":20,
"Items":[
...
]
}
This response indicates that all events fall into two distinct categories: Sales & Marketing (category 9035) and Leadership (category 9032), which have a count of 16 and 11 events, respectively. To drill down and see a list of these events inside each category, the response indicates the filter code to use is templatecategoryid, and possible values are 9035 and 9032. For example, a followup API request could be:
GET /api/2012-02-01/pub/resources/eventsearch/?format=json&filter=templatecategoryid=9032
This request would produce a resultset of exactly 11 events corresponding to the count of 11 indicated by the facet entry for this category.
Facet-only requests
If your request to the endpoint is just to retrieve facet data and not actual results in the response Items array, include the parameter top=0 in your request to truncate the results count to zero. For example:
GET /api/2012-02-01/pub/resources/eventsearch/?format=json&facets=templatecategory(top=10,orderby=count)&top=0
{
"Facets":[
{
"Name":"Category",
"Code":"templatecategory",
"FilterCode":"templatecategoryid",
"ValuesCount":3,
"Values":[
{
"Label":"Sales & Marketing",
"Code":"9035",
"Count":16
},
{
"Label":"Leadership",
"Code":"9032",
"Count":11
},
{
"Label":"Accounting & Finance",
"Code":"9030",
"Count":10
}
]
}
],
"StartIndex":0,
"Count":0,
"Items":[]
}
This request will still return facets for templatecategory, but it won't bother returning any actual Items results.
Examples
Example 1
Retrieve facet values for the top 10 distinct event categories associated with upcoming events (using templatecategory facet code), sorted by the count of events. This example is a typical method of retrieving a list of event template categories and counts of upcoming events within each.
GET /api/2012-02-01/pub/resources/eventsearch/?format=json&facets=templatecategory(top=10,orderby=count)
{
"Facets":[
{
"Name":"Category",
"Code":"templatecategory",
"FilterCode":"templatecategoryid",
"ValuesCount":7,
"Values":[
{
"Label":"Sales & Marketing",
"Code":"9035",
"Count":16
},
{
"Label":"Leadership",
"Code":"9032",
"Count":11
},
{
"Label":"Accounting & Finance",
"Code":"9030",
"Count":10
},
{
"Label":"Project Management",
"Code":"9033",
"Count":10
},
{
"Label":"Certifications & Licences",
"Code":"9036",
"Count":7
},
{
"Label":"Communication",
"Code":"9031",
"Count":6
},
{
"Label":"Management",
"Code":"9034",
"Count":6
}
]
}
],
"StartIndex":0,
"Count":20,
"Items":[
...
]
}
Note the response above does not show the content Items array for simplicity as the example is designed to illustrate the Facets part of the response payload and not the actual results.
Example 2
Retrieve facet values for all cities (using city facet code) where events for the BENCH template will run, sorted by city name (alphabetical). This example is a typical method of retrieving a list of possible cities that a user might want to choose from to filter a list of events.
This example also illustrates the use of the facetsfilter parameter to restrict the dataset used to only events from the BENCH template when producing city facet values.
GET /api/2012-02-01/pub/resources/eventsearch/?format=json&facets=city(orderby=label)&facetsfilter=templatecode=BENCH
{
"Facets":[
{
"Name":"City",
"Code":"city",
"FilterCode":"citycode",
"ValuesCount":3,
"Values":[
{
"Label":"Auckland",
"Code":"Auckland",
"Count":18
},
{
"Label":"Christchurch",
"Code":"Christchurch",
"Count":12
},
{
"Label":"Wellington",
"Code":"Wellington",
"Count":11
}
]
}
],
"StartIndex":0,
"Count":20,
"Items":[
...
]
}