Comment on page
Filter entity lists
Filters narrow the list down to just entities that meet a particular condition--specifically, a particular value for a particular attribute.
A list of filters are set using the
filter parameter, formatted like this: filter=attribute:value,attribute2:value2. Examples:- Get the authors whose name is Einstein:
https://api.openalex.org/authors?filter=display_name.search:einstein
Filters are case-insensitive.
For numerical filters, use the less-than (
<) and greater-than (>) symbols to filter by inequalities. Example:- Get sources that host more than 1000 works:
https://api.openalex.org/sources?filter=works_count:>1000
Some attributes have special filters that act as syntactic sugar around commonly-expressed inequalities: for example, the
from_publication_date filter on works. See the endpoint-specific documentation below for more information. Example:- Get all works published between 2022-01-01 and 2022-01-26 (inclusive):
https://api.openalex.org/works?filter=from_publication_date:2022-01-01,to_publication_date:2022-01-26
You can negate any filter, numerical or otherwise, by prepending the exclamation mark symbol (
!) to the filter value. Example:- Get all institutions except for ones located in the US:
https://api.openalex.org/institutions?filter=country_code:!us
By default, the returned result set includes only records that satisfy all the supplied filters. In other words, filters are combined as an AND query. Example:
- Get all works that have been cited more than once and are free to read:
https://api.openalex.org/works?filter=cited_by_count:>1,is_oa:true
To create an AND query within a single attribute, you can either repeat a filter, or use the plus symbol (
+):- Get all the works that have an author from France and an author from the UK:
- Using repeating filters:
https://api.openalex.org/works?filter=institutions.country_code:fr,institutions.country_code:gb
Note that the plus symbol (
+) syntax will not work for search filters, boolean filters, or numeric filters.Use the pipe symbol (
|) to input lists of values such that any of the values can be satisfied--in other words, when you separate filter values with a pipe, they'll be combined as an OR query. Example:- Get all the works that have an author from France or an author from the UK:
https://api.openalex.org/works?filter=institutions.country_code:fr|gb
This is particularly useful when you want to retrieve a many records by ID all at once. Instead of making a whole bunch of singleton calls in a loop, you can make one call, like this:
- Get the works with DOI
10.1371/journal.pone.0266781or with DOI10.1371/journal.pone.0267149(note the pipe separator between the two DOIs):https://api.openalex.org/works?filter=doi:https://doi.org/10.1371/journal.pone.0266781|https://doi.org/10.1371/journal.pone.0267149
You can use OR for values within a given filter, but not between different filters. So this, for example, doesn't work and will return an error:
- Get either French works or ones published in the journal with ISSN 0957-1558:
https://api.openalex.org/works?filter=institutions.country_code:fr|primary_location.source.issn:0957-1558
The filters for each entity can be found here:
Last modified 1mo ago