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:

Filters are case-insensitive.

Logical expressions

Inequality

For numerical filters, use the less-than (<) and greater-than (>) symbols to filter by inequalities. Example:

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:

Negation (NOT)

You can negate any filter, numerical or otherwise, by prepending the exclamation mark symbol (!) to the filter value. Example:

Intersection (AND)

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 (+):

Note that the plus symbol (+) syntax will not work for search filters, boolean filters, or numeric filters.

Addition (OR)

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 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 blog post for a tutorial.

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:

Available Filters

The filters for each entity can be found here:

Last updated