Aggregations

V4 offers two aggregation modes that replace the previous includeStats parameter. Both modes 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.

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/research-products?search=covid&facets=type,best_oa.rights,language&page_size=5

Response:

{
  "header": {
    "numFound": 245891,
    "page": 1,
    "pageSize": 5
  },
  "results": [
    ... 5 records ...
  ],
  "facets": {
    "type": {
      "publication": 180432,
      "dataset": 52100,
      "software": 8910,
      "other": 4449
    },
    "best_oa.rights": {
      "Open Access": 120000,
      "Closed Access": 80000,
      "Embargo": 30000
    },
    "language": {
      "English": 190000,
      "German": 12000,
      "French": 9500
    }
  }
}

note

Facet counts reflect the entire matching result set, not just the page of records returned. This is how you can show a user 5 results per page while displaying the full distribution across types, years, and access rights.

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/research-products?filter=from_publication_year:2023,to_publication_year:2023&group_by=type

Response:

{
  "header": {
    "numFound": 1693826
  },
  "results": [],
  "facets": {
    "type": {
      "publication": 1200000,
      "dataset": 350000,
      "software": 95000,
      "other": 48826
    }
  }
}

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 — datasets from 2020+, with facet counts by country and funder:

/v4/research-products?filter=type:dataset,from_publication_year:2020&facets=authorships.countries,grants.funder_short_name&page_size=10

Example — OA color distribution for EC-funded publications (no records needed):

/v4/research-products?filter=type:publication,grants.funder_short_name:EC&group_by=oa_color

caution

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