Last updated
Last updated
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 . To do that, you call the entity endpoint, adding the group_by
parameter. Example:
Get counts of works by type:
This returns a meta
object with details about the query, and a group_by
object with the groups you've asked for:
So from this we can see that the majority of works (202,814,957 of them) are type article
, with another 21,250,659 book-chapter
, and so forth.
Each group object in the group_by
list contains three properties:
key
key_display_name
count
Value: an integer; the number of entities in the group.
The "unknown" group is hidden by default. If you want to include this group in the response, add :include_unknown
after the group-by parameter.
key
and key_display_name
Otherwise, key
is the same as key_display_name
; both are the raw value of the group_by
parameter for this group.
For one group, both key
and key_display_name
are "3".
meta
propertiesmeta.count
is the total number of works (this will be all works if no filter is applied). meta.groups_count
is the count of groups (in the current page).
If there are no groups in the response, meta.groups_count
is null
.
Due to a technical limitation, we can only report the number of groups in the current page, and not the total number of groups.
Due to technical constraints, when paging, results are sorted by key, rather than by count.
You can group by most of the same properties that you can by, and you can combine grouping with filtering.
Value: a string; the or raw value of the group_by
parameter for members of this group. See details on .
Value: a string; the display_name
or raw value of the group_by
parameter for members of this group. See details on .
Group works by (unknown group hidden):
Group works by (includes unknown group):
If the value being grouped by is an OpenAlex Entity
, the and properties will be that Entity
's id
and display_name
, respectively.
Group Works
by Institution
:
For one group, key
is "" and key_display_name
is "Harvard University".
Group Concepts
by :
The maximum number of groups returned is 200. If you want to get more than 200 groups, you can use cursor pagination. This works the same as it does when getting lists of entities, so to learn how.