Filter entity lists
Last updated
Last updated
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 works whose is book:
Get the authors whose name is 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:
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):
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:
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:
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:
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:
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:
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:
The filters for each entity can be found here:
Get all works that have been cited more than once and are free to read:
Using repeating filters:
Using the plus symbol (+):
Get all the works that have an author from France or an author from the UK:
Get the works with DOI 10.1371/journal.pone.0266781 or with DOI 10.1371/journal.pone.0267149 (note the pipe separator between the two DOIs):
You can combine up to 100 values for a given filter in this way. You will also need to use the parameter per-page=100 to get all of the results per query. See our for a tutorial.
Get either French works or ones published in the journal with ISSN 0957-1558: