Faceted counts for an agenda's events — native facets plus its `additionalFields`

Numeric uid of the agenda.

Comma-separated list of facets to compute over the filtered events. Unknown facet names return 400. Each facet's result shape is defined by FacetResults. Bucket-list facets (the term, provenance and locations families) return the top buckets by event count, capped by facetSize (overridable per facet with facetSizes[<facet>]) and reordered by facetSort; past the cap, narrow the filter. additionalFields and additionalFieldMetrics cover the agenda's own fields as its event form schema declares them (GET /agendas/{agendaUid}/events/schema), named by additionalFieldsKeys/additionalFieldMetricsKeys or all readable fields when omitted; additionalFields returns one bucket per option. timings bucket width is set by timingsInterval, the dateRanges month by month, geohash granularity by geohashZoom.

Default maximum number of buckets for the bucket-list facets (the term, provenance and locations families), ordered by event count. Override a single facet with facetSizes[<facet>]. Out-of-range values are clamped; other facets ignore it.

Per-facet override of facetSize, keyed by facet name (facetSizes[cities]=50). Precedence: per-facet override > facetSize > default (10). Only applies to bucket-list facets; values are clamped to [1, 250].

Default ordering of the bucket-list facets. count (default) returns the most frequent buckets first; alpha returns the same top-facetSize buckets but ordered alphabetically by their display value (city/keyword name, location name, agenda title) for readable scanning. Override a single facet with facetSorts[<facet>].

Per-facet override of facetSort, keyed by facet name (facetSorts[cities]=alpha). Precedence: per-facet override > facetSort > default (count).

Per-facet label for a synthetic bucket counting the filtered events that have no value for the facet's field (facetMissing[district]=Unknown adds an { value: "Unknown", count } bucket). Honoured by the term facets (those whose buckets are keyed by the displayed value) except accessibilities; ignored by the provenance, locations and remaining families. The bucket appears only when such events exist.

Clustering zoom level for the geohash facet (higher = finer grid, more clusters). Ignored unless geohash is requested.

Bucket width for the timings date histogram. Ignored unless timings is requested; an unrecognized value falls back to day.

Calendar month (YYYY-MM) the dateRanges facet buckets day-by-day. Defaults to the current month; an unrecognized value falls back to it. Ignored unless dateRanges is requested. Because it bounds the buckets by scoping the filtered set to that month, it also constrains any other facet requested in the same call.

Comma-separated agenda choice/boolean field names to compute the additionalFields facet on — the names the agenda's event form schema declares (GET /agendas/{agendaUid}/events/schema). Omit to get every such field readable at the caller's access level. An unknown or non-readable field name returns 400. Ignored unless additionalFields is requested.

Comma-separated agenda numeric field names to compute the additionalFieldMetrics facet on — the names the agenda's event form schema declares (GET /agendas/{agendaUid}/events/schema). Omit to get every numeric field readable at the caller's access level. An unknown or non-readable field name returns 400. Ignored unless additionalFieldMetrics is requested.

Full-text search across title, description, keywords and address. Wrap the value in double quotes for an exact phrase match.

Relevance score floor for search results, used to drop weakly-matching events from the long tail (e.g. a single query term buried in a long description). Ignored when search is not set. off (the default) returns every match. auto derives the floor from the score distribution of the current query: the largest relative drop ("elbow") in the top scores becomes the cutoff, so it adapts to each query. A non-negative number is an absolute minimum score; relevance scores are specific to a query, so a fixed value suits a single tuned query rather than general use - prefer auto. The cutoff applies before counting, so the returned events, their total and the facet counts describe the same trimmed set; pass the same threshold to the facets endpoint to keep its counts aligned with the list.

Restrict to these event uids. Repeat the parameter for multiple values.

Restrict to these event slugs. Repeat the parameter for multiple values.

Match an event by an external identifier: extId[key]=<system>&extId[value]=<id>.

Restrict to events tagged with these keywords. Repeating the parameter narrows the result set (AND semantics).

Restrict to events in these languages (ISO 639-1 codes).

Restrict to events offering these accessibility facilities.

Restrict to these statuses.

Restrict to these attendance modes.

Restrict to featured (true) or non-featured (false) events.

Restrict to events held at these location uids.

Match by a location external identifier: locationExtId[key]=<system>&locationExtId[value]=<id>.

Restrict to events located in these regions.

Restrict to events located in these departments.

Restrict to events located in these cities.

Restrict to events located in these districts.

Restrict to events located in these level-3 administrative areas.

Restrict to events located in these level-5 administrative areas.

Restrict to events located in these countries (ISO 3166-1 alpha-2).

Restrict to events whose location falls within a bounding box, given as west,south,east,north in decimal degrees (WGS84). Example: bbox=2.224,48.815,2.469,48.902.

Center of a proximity search, given as latitude,longitude in decimal degrees. Must be combined with radius.

Proximity radius in metres around near. Requires near to be set.

Restrict to events originally created in these agendas.

Restrict to events whose origin agenda is official (true) or not (false).

Restrict to events aggregated from these source agendas.

Restrict by temporal position relative to now. Combine values (repeat the parameter) to widen the window: passed, upcoming, current.

Restrict to events having a timing that begins within the range, as RFC 3339 date-times: timings[gte]=…&timings[lte]=…. For now-relative windows, prefer relative. Date-times must carry an explicit offset (e.g. Z); a bare date (YYYY-MM-DD) is read as UTC midnight.

Restrict to events with a timing starting within a daily time window, in minutes from local midnight: localTime[gte]=480 (08:00) and/or localTime[lte]=1200 (20:00).

Restrict by creation date, as RFC 3339 date-times: createdAt[gte]=…&createdAt[lte]=…. Date-times must carry an explicit offset (e.g. Z); a bare date (YYYY-MM-DD) is read as UTC midnight.

Restrict by last-update date, as RFC 3339 date-times: updatedAt[gte]=…&updatedAt[lte]=…. Useful for incremental sync. Date-times must carry an explicit offset (e.g. Z); a bare date (YYYY-MM-DD) is read as UTC midnight.

Restrict by the date OpenAgenda last WROTE inventory on the event — the write clock carried by availabilityUpdatedAt, not the rows' own syncedAt. As RFC 3339 date-times: availabilityUpdatedAt[gte]=…&availabilityUpdatedAt[lte]=…. The inventory counterpart of updatedAt, for a consumer following availability: pair it with sort=availabilityUpdatedAt.asc and a watermark. Events that never received availability carry no stamp and never match — following inventory does not mean paging through the whole corpus. Same date-time rules as updatedAt.

Restrict to events whose intended audience age range overlaps the given bounds, in years: age[gte]=7&age[lte]=12.

Filter on agenda-specific additional fields, addressed by field name: additionalFields[<fieldName>]=<value>. Available fields and their value types come from the agenda's event form schema (GET /agendas/{agendaUid}/events/schema). For numeric fields, use a range object: additionalFields[<fieldName>][gte]=…&additionalFields[<fieldName>][lte]=….