Sign in
Events

Named, repeatable facet aggregations for an agenda's events

Changed on

Takes a JSON body of named, repeatable aggregations: the same facet type may appear several times under distinct name aliases, so a field can be aggregated several ways in one request (e.g. timings by month AND by year). Filters live under filters (an EventFilters object) and scope every facet.

Each facet item is either a bare facet name or a FacetSpec object carrying per-instance options; facetSize/facetSort at the top level set the request-wide defaults an item overrides. The response is keyed by alias, each entry tagged with its type so the value shape is unambiguous. Only published events are counted.

post/agendas/{agendaUid}/events/facets

Request

  • Base URL: https://api.openagenda.com/v3
  • URL: https://api.openagenda.com/v3/agendas/{agendaUid}/events/facets
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://openagenda.com/api/auth/oauth2/authorize, token URL https://openagenda.com/api/auth/oauth2/token, scopes: events:read)

Path parameters

agendaUidinteger required

Numeric uid of the agenda.

Request body

facetSizeinteger

Request-wide default bucket size; a facet's own size overrides it.

facetSort'count' | 'alpha'

Request-wide default order; a facet's own sort overrides it.

Example request

{
  "filters": {
    "keyword": [
      "concert"
    ]
  },
  "facets": [
    "cities",
    {
      "name": "topKeywords",
      "type": "keywords",
      "size": 20,
      "sort": "count"
    },
    {
      "name": "byMonth",
      "type": "timings",
      "interval": "month"
    },
    {
      "name": "byYear",
      "type": "timings",
      "interval": "year"
    }
  ]
}

Response

Named facet results over the filtered set.

facetsobject required

One entry per requested facet, keyed by its name alias.

Example response

{
  "facets": {
    "cities": {
      "type": "cities",
      "result": [
        {
          "value": "Lyon",
          "count": 42
        }
      ]
    },
    "byMonth": {
      "type": "timings",
      "result": [
        {
          "value": "2025-06",
          "count": 18
        },
        {
          "value": "2025-07",
          "count": 31
        }
      ]
    }
  }
}

Changes

  • 948e1d1c57f3Revision changes
    • info

      added the optional property /////// to the response with the status

  • 5f5fbbc78c13Revision changes
    • info

      added the new optional request property /