Comment on page
Get groups of entities
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, and a group_by object with the groups you've asked for:{
meta: {
count: 246136992,
db_response_time_ms: 271,
page: 1,
per_page: 200,
groups_count: 15
},
group_by: [
{
key: "article",
key_display_name: "article",
count: 202814957
},
{
key: "book-chapter",
key_display_name: "book-chapter",
count: 21250659
},
{
key: "dissertation",
key_display_name: "dissertation",
count: 6055973
},
{
key: "book",
key_display_name: "book",
count: 5400871
},
...
]
}
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.You can group by most of the same properties that you can filter by, and you can combine grouping with filtering.
Each group object in the
group_by list contains three properties: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.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.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.- Group works by
authorships.countries(unknown group hidden):https://api.openalex.org/works?group_by=authorships.countries - Group works by
authorships.countries(includes unknown group):https://api.openalex.org/works?group_by=authorships.countries:include_unknown
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.- For one group,
keyis "https://openalex.org/I136199984" andkey_display_nameis "Harvard University".
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
keyandkey_display_nameare "3".
meta.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.
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 head over to the section on paging through lists of results to learn how.
Due to technical constraints, when paging, results are sorted by key, rather than by count.
Last modified 23d ago