Skip to main content
Version: Next

Sorting and paging

The OpenAIRE Graph API allows you to sort and page through the results of your search queries. This enables you to retrieve the most relevant results and manage large result sets more effectively.

Sorting​

Sorting based on specific fields, helps to retrieve data in the preferred order. Sorting is achieved using the sortBy parameter, which specifies the field and the direction (ascending or descending) for sorting.

  • sortBy: Defines the field and the sort direction. The format should be fieldname sortDirection, where the sortDirection can be either ASC for ascending order or DESC for descending order.

The field names that can be used for sorting are specific to each entity type and can be found in the sortBy field values of the available paremeters.

Note that the default sorting is based on the relevance score of the search results.

Examples:

Note that you can combine multiple sorting conditions by separating them with a comma.

Example:

Paging​

The OpenAIRE Graph API supports basic and cursor-based pagination. In basic pagination, page and pageSize parameters are used, enabling you to specify which part of the result set to retrieve and how many results per page.

Offset-based paging​

Offset-based paging should be used to retrieve a small dataset only (up to 10000 records).

  • page: Specifies the page number of the results you want to retrieve. Page numbering starts from 1.

  • pageSize: Defines the number of results to be returned per page. This helps limit the amount of data returned in a single request, making it easier to process.

Example:

response:

{
    header: {
        numFound: 36818386,
        maxScore: 1,
        queryTime: 21,
        page: 1,
        pageSize: 10
    },
    results: [
        ...
    ]
}

Cursor-based paging​

Cursor should be used when it is required to retrieve a big dataset (more than 10000 records).

  • cursor: Cursor-based pagination. Initial value: cursor=*.

Example:

response:

{
    header: {
        numFound: 36818386,
        maxScore: 1,
        queryTime: 21,
        pageSize: 10,
        nextCursor: "AoI/D2M2NGU1YjVkNTQ4Nzo6NjlmZTBmNjljYzM4YTY1MjI5YjM3ZDRmZmIyMTU1NDAIP4AAAA=="
    },
    results: [
        ...
    ]
}

Use nextCursor value, to get the next page of results.