Get groups of entities
See the API overview for info on pagination, authentication, etc.
Sometimes instead of just listing entities, you want to group them into facets, and count how many entities are in each group. For example, maybe you want to count the number of Works by open access status. To do that, you call the entity endpoint, adding the ?group_by parameter. Example:
This returns a meta object with details about the query, an empty results object, and a group_by object with the groups you've asked for:
1
{
2
meta: {
3
count: 6,
4
db_response_time_ms: 26,
5
page: 1,
6
per_page: 200
7
},
8
results: [ ],
9
group_by: [
10
{
11
key: "unknown",
12
key_display_name: "unknown",
13
count: 110691108
14
},
15
{
16
key: "closed",
17
key_display_name: "closed",
18
count: 66862508
19
},
20
{
21
key: "gold",
22
key_display_name: "gold",
23
count: 11087903
24
},
25
{
26
key: "bronze",
27
key_display_name: "bronze",
28
count: 10499470
29
},
30
{
31
key: "green",
32
key_display_name: "green",
33
count: 6918466
34
},
35
{
36
key: "hybrid",
37
key_display_name: "hybrid",
38
count: 3277958
39
}
40
]
41
}
Copied!
So from this we can see that the majority of works (66,862,508 of them) are closed, with another 10,499,470 bronze, and so forth.
You can group by most of the same properties that you can filter by, and you can combine grouping with filtering.

Group properties

Each group object in the group_by list contains three properties:

key

Value: a string; the OpenAlex ID or raw value of the group_by parameter for members of this group. See details on key and key_display_name.

key_display_name

Value: a string; the display_name or raw value of the group_by parameter for members of this group. See details on key and key_display_name.

count

Value: an integer; the number of entities in the group.

key and key_display_name

If the value being grouped by is an OpenAlex Entity, the key and key_display_name properties will be that Entity's id and display_name, respectively.
Otherwise, key is the same as key_display_name; both are the raw value of the group_by parameter for this group.

Groupable attributes

Each Entity type has a different set of attributes you can group by. These are mostly the same as the filterable attributes - excluding two main types of filters:
  • Dates like to_publication_date that only make sense for filtering because there isn't a single value that belongs to each entity.
  • Wide-ranging numeric attributes like cited_by_count with high cardinality. Grouping on these values produces too many groups to be useful.

/works group_by attributes

/authors group_by attributes

/venues group_by attributes

/institutions group_by attributes

/concepts group_by attributes

Sorting groups

You can sort grouped by results using count or key. The default is count:desc.

Pagination

You cannot page through grouped results using page or per-page. You will always receive one page of results and per-page is fixed at 200.
This means 200 is the maximum number of groups that can be returned - https://api.openalex.org/works?group_by=host_venue.publisher will only provide work counts for the top 200 publishers.

Combining grouping with filtering

The group_by and filter parameters can be used at the same time. If you use both parameters, only the Entities matched by filter will be grouped and counted.
This gives you the overall count of open and closed Works in OpenAlex. About 68% are OA at the moment.
Combining this with the filter type:journal-article gives you the same count, but for journal articles only.
Journal articles are about 51% OA.
You can filter using all the available logical expressions, just as if you weren't grouping.