Aggregations

V4 offers two aggregation modes. Both return facet counts — bucket breakdowns showing how many results match each value of a given field.

Any field marked as Facetable in the filter fields reference is eligible for aggregation. For projects these are: call_identifier, funder, funder_short_name, country, oa_mandate_publications, start_year, end_year, organizations.id, organizations.country, communities.id, collected_from.id.

facets — records + aggregations

Returns the normal paginated result set plus facet counts for the specified fields. Use this when you want to display search results alongside filter sidebar counts.

Provide a comma-separated list of facetable field names:

/v4/projects?search=climate&facets=funder_short_name,start_year&page_size=5

Response:

{
  "header": {
    "numFound": 18230,
    "page": 1,
    "pageSize": 5
  },
  "results": [
    ... 5 records ...
  ],
  "facets": {
    "funder_short_name": {
      "EC": 7200,
      "NSF": 3100,
      "UKRI": 1900
    },
    "start_year": {
      "2023": 2100,
      "2022": 1900,
      "2021": 1750
    }
  }
}

note

Facet counts reflect the entire matching result set, not just the page of records returned.

group_by — facets only

Returns only aggregation buckets with no records. Use this for analytics, dashboards, or data exploration when you only need the counts.

Provide a single facetable field name:

/v4/projects?filter=active_year:2024&group_by=funder_short_name

Response:

{
  "header": {
    "numFound": 292100
  },
  "results": [],
  "facets": {
    "funder_short_name": {
      "EC": 41000,
      "NIH": 32000,
      "NSF": 21000
    }
  }
}

Combining filters with aggregations

You can use facets together with any filter, search, or sort parameter. The facet counts always reflect the filtered result set.

Example — EC projects counted by start year:

/v4/projects?filter=funder_short_name:EC&group_by=start_year

caution

facets and group_by are mutually exclusive. Sending both in the same request returns a 400 error.