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 data sources these are: type, subjects, content_types, eosc_datasource_type, jurisdiction, thematic, od_languages, country, compatibility.id, compatibility.name, organizations.id, 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/datasources?search=repository&facets=type,country&page_size=5

Response:

{
  "header": {
    "numFound": 42100,
    "page": 1,
    "pageSize": 5
  },
  "results": [
    ... 5 records ...
  ],
  "facets": {
    "type": {
      "Repository": 28000,
      "Journal": 9800,
      "Aggregator": 2100
    },
    "country": {
      "US": 6100,
      "DE": 3900,
      "GB": 3200
    }
  }
}

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/datasources?group_by=type

Response:

{
  "header": {
    "numFound": 119742
  },
  "results": [],
  "facets": {
    "type": {
      "Repository": 62000,
      "Journal": 41000,
      "Aggregator": 8900
    }
  }
}

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 — repositories counted by country:

/v4/datasources?filter=type:Repository&group_by=country

caution

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