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 organizations these are: 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/organizations?search=university&facets=country&page_size=5

Response:

{
  "header": {
    "numFound": 35721,
    "page": 1,
    "pageSize": 5
  },
  "results": [
    ... 5 records ...
  ],
  "facets": {
    "country": {
      "US": 8210,
      "GB": 4110,
      "DE": 3050
    }
  }
}

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/organizations?group_by=country

Response:

{
  "header": {
    "numFound": 184213
  },
  "results": [],
  "facets": {
    "country": {
      "US": 32100,
      "GB": 15400,
      "DE": 12800
    }
  }
}

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 — organizations in the EGI community, counted by country:

/v4/organizations?filter=communities.id:egi&group_by=country

caution

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