Old OpenAlex API documentation
  • Overview
  • Quickstart tutorial
  • API Entities
    • Entities overview
    • 📄Works
      • Work object
        • Authorship object
        • Location object
      • Get a single work
      • Get lists of works
      • Filter works
      • Search works
      • Group works
      • Get N-grams
    • 👩Authors
      • Author object
      • Get a single author
      • Get lists of authors
      • Filter authors
      • Search authors
      • Group authors
      • Limitations
      • Author disambiguation
    • 📚Sources
      • Source object
      • Get a single source
      • Get lists of sources
      • Filter sources
      • Search sources
      • Group sources
    • 🏫Institutions
      • Institution object
      • Get a single institution
      • Get lists of institutions
      • Filter institutions
      • Search institutions
      • Group institutions
    • 💡Topics
      • Topic object
      • Get a single topic
      • Get lists of topics
      • Filter topics
      • Search topics
      • Group topics
    • 🗝️Keywords
    • 🏢Publishers
      • Publisher object
      • Get a single publisher
      • Get lists of publishers
      • Filter publishers
      • Search publishers
      • Group publishers
    • 💰Funders
      • Funder object
      • Get a single funder
      • Get lists of funders
      • Filter funders
      • Search funders
      • Group funders
    • 🌎Geo
      • Continents
      • Regions
    • 💡Concepts
      • Concept object
      • Get a single concept
      • Get lists of concepts
      • Filter concepts
      • Search concepts
      • Group concepts
    • Aboutness endpoint (/text)
  • How to use the API
    • API Overview
    • Get single entities
      • Random result
      • Select fields
    • Get lists of entities
      • Paging
      • Filter entity lists
      • Search entities
      • Sort entity lists
      • Select fields
      • Sample entity lists
      • Autocomplete entities
    • Get groups of entities
    • Rate limits and authentication
  • Download all data
    • OpenAlex snapshot
    • Snapshot data format
    • Download to your machine
    • Upload to your database
      • Load to a data warehouse
      • Load to a relational database
        • Postgres schema diagram
  • Additional Help
    • Tutorials
    • Report bugs
    • FAQ
Powered by GitBook
On this page
  • Group properties
  • "Unknown" groups
  • key and key_display_name
  • Group-by meta properties
  • Paging
  1. How to use the API

Get groups of entities

PreviousAutocomplete entitiesNextRate limits and authentication

Last updated 1 year ago

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:

{
    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.

Group properties

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.

"Unknown" groups

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".

Group-by meta properties

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.

Paging

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.

filter
https://api.openalex.org/works?group_by=authorships.institutions.id
https://openalex.org/I136199984
key and key_display_name
key
key_display_name
key and key_display_name
OpenAlex ID
https://api.openalex.org/works?group_by=type
open access status
https://api.openalex.org/concepts?group_by=level
level
https://api.openalex.org/works?group_by=authorships.countries
authorships.countries
https://api.openalex.org/works?group_by=authorships.countries:include_unknown
authorships.countries
head over to the section on paging through lists of results