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 venues that host more than 1000 works:
https://api.openalex.org/venues?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 - Get all the works that have an author from France and an author from the UK:
https://api.openalex.org/works?filter=institutions.country_code:fr,institutions.country_code:gb
You can repeat a filter to create an AND query within a single attribute. Example:
- Get all works that have concepts "Medicine" and "Artificial Intelligence":
https://api.openalex.org/works?filter=concepts.id:C71924100,concepts.id:C154945302
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 combine up to 50 values for a given filter in this way.
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|host_venue.issn:0957-1558
You can filter using these attributes of the
Work entity object (click each one to view their documentation on the Work entity page):These filters aren't attributes of the
Work entity object, but they're handy for solving some common use cases:Value: a search string
Returns: works whose
display_name (title) includes the given string; see the search filter for details. - Get works with titles that mention the word "wombat":
https://api.openalex.org/works?filter=title.search:wombat
For most cases, you should use the
search parameter instead of this filter, because it uses a better search algorithm and searches over abstracts as well as titles.Value: a search string
Returns: works whose abstract includes the given string. See the search filter for details on the search algorithm used.
- Get works with abstracts that mention "artificial intelligence":
https://api.openalex.org/works?filter=abstract.search:artificial%20intelligence
Value: a search string
Returns: works whose fulltext includes the given string. Fulltext search is powered by an index of word sequences called n-grams - see Get N-grams for coverage details.
- Get works with fulltext that mention "climate change":
https://api.openalex.org/works?filter=fulltext.search:climate%20change
Value: a search string
Returns: works that have at least one
raw_affiliation_string which includes the given string. See the search filter for details on the search algorithm used. - Get works with the words Department of Political Science, University of Amsterdam somewhere in at least one author's
raw_affiliation_string:https://api.openalex.org/works?filter=raw_affiliation_string.search:department%20of%20political%20science%20university%20of%amsterdam
Value: a Boolean (
true or false)Returns: works that have or lack an abstract, depending on the given value.
Value: a Boolean (
true or false)Returns: works that have or lack a DOI, depending on the given value. It's especially useful for grouping.
Value: a Boolean (
true or false)Returns: if
true it returns works where at least one author or has an ORCID ID. If false, it returns works where no authors have an ORCID ID. This is based on the orcid field within authorships.author.- Get the works where at least one author has an ORCID ID:
https://api.openalex.org/works?filter=has_orcid:true
Value: a Boolean (
true or false)Value: a Boolean (
true or false)Value: a Boolean (
true or false)Returns: works for which n-grams are available or unavailable, depending on the given value. N-grams power fulltext searches through the
fulltext.search filter and the search parameter.Value: a Boolean (
true or false)Returns: works that cite the given work. This is works that have the given OpenAlex ID in the
referenced_works section. You can think of this as incoming citations. - Get works that cite https://openalex.org/W2741809807:
https://api.openalex.org/works?filter=cites:W2741809807
The number of results returned by this filter may be slightly higher than the work's
cited_by_countdue to a timing lag in updating that field. Returns: works found in the given work's
referenced_works section. You can think of this as outgoing citations. - Get works related to https://openalex.org/W2486144666:
https://api.openalex.org/works?filter=related_to:W2486144666
Value: a date, formatted as
yyyy-mm-dd- Get works published on or after March 14th, 2001:
https://api.openalex.org/works?filter=from_publication_date:2001-03-14
Value: a date, formatted as
yyyy-mm-dd- Get works published on or before March 14th, 2001:
https://api.openalex.org/works?filter=to_publication_date:2001-03-14
Value: a Boolean (
true or false)Returns: works with at least one
host_venue or alternate_host_venue where is_oa= true and version is acceptedVersion or publishedVersion. For Works that undergo peer review, like journal articles, this means there is a peer-reviewed OA copy somewhere. For some items, like books, a published version doesn't imply peer review, so they aren't quite synonymous.- Get works with an OA accepted or published copy
https://api.openalex.org/works?filter=has_oa_accepted_or_published_version:true
Value: a Boolean (
true or false)Returns: works with at least one
host_venue or alternate_host_venue where is_oa= true and version is submittedVersion. This is useful for finding works with preprints deposited somewhere.- Get works with an OA submitted copy:
https://api.openalex.org/works?filter=has_oa_submitted_version:true
Returns: works where at least one of the author's institutions is in the chosen continent (read more).
- Get works where at least one author's institution in each work is located in Europe https://api.openalex.org/works?filter=authorships.institutions.continent:europe
Value: a Boolean (
true or false)- Get works where at least one author's institution is in the Global South https://api.openalex.org/works?filter=authorships.institutions.is_global_south:true
Returns: works where the chosen venue ID exists within the host_venue or the alternate_host_venues objects.
You can use this to find works where authors are associated with your university, but the work is not part of the university's repository.
👏
- Get works that are available in the University of Michigan Deep Blue repository (OpenAlex ID: https://openalex.org/V4306400393) https://api.openalex.org/works?filter=repository:V4306400393
- Get works where at least one author is associated with the University of Michigan, but the works are not found in the University of Michigan Deep Blue repository https://api.openalex.org/works?filter=institutions.id:I27837315,repository:!V4306400393
Value: a String with value
publishedVersion, submittedVersion, acceptedVersion, or nullReturns: works where the chosen version exists within the host_venue or the alternate_host_venues objects. If
null, it returns works where no version is found in either location.- Get works where a published version is available in the host venue or alternate host venues https://api.openalex.org/works?filter=version:publishedVersion
Value: an Integer
Returns: works with the chosen number of
authorships objects (authors). You can use the inequality filter to select a range, such as authors_count:>5.Value: an Integer
- Get works with at least three concepts assigned https://api.openalex.org/works?filter=concepts_count:>2
You can filter using these attributes of the
Author entity object (click each one to view their documentation on the Author entity page):These filters aren't attributes of the
Author entity object, but they're included to address some common use cases:Value: a search string
In most cases, you should use the
search parameter instead of this filter because it uses a better search algorithm.Value: a Boolean (
true or false)- Get authors where the last known institution is located in Africa https://api.openalex.org/authors?filter=last_known_institution.continent:africa
Value: a Boolean (
true or false)- Get authors where the last known institution is located in the Global South https://api.openalex.org/authors?filter=last_known_institution.is_global_south:true
You can filter using these attributes of the
Venue entity object (click each one to view their documentation on the Venue entity page):These filters aren't attributes of the
Venue entity object, but they're included to address some common use cases:Value: a search string
- Get venues with names containing "Neurology":
https://api.openalex.org/venues?filter=display_name.search:Neurology
In most cases, you should use the
search parameter instead of this filter because it uses a better search algorithm.Value: a Boolean (
true or false)Value: a Boolean (
true or false)- Get venues that are located in the Global South https://api.openalex.org/venues?filter=is_global_south:true
You can filter using these attributes of the
Institution entity object (click each one to view their documentation on the Institution entity page):These filters aren't attributes of the
Institution entity object, but they're included to address some common use cases:Value: a search string
Returns: institutions with a display_name containing the given string; see the search filter for details.
- Get institutions with names containing "technology":
https://api.openalex.org/institutions?filter=display_name.search:technology
In most cases, you should use the search parameter instead of this filter because it uses a better search algorithm.
Value: a Boolean (
true or false)- Get institutions that are located in South America https://api.openalex.org/institutions?filter=continent:south_america
Value: a Boolean (
true or false)- Get institutions that are located in the Global South https://api.openalex.org/institutions?filter=is_global_south:true
You can filter using these attributes of the
Concept entity object ((click each one to view their documentation on the Concept entity page):These filters aren't attributes of the
Concept entity object, but they're included to address some common use cases:Value: a search string
Returns: concepts with a display_name containing the given string; see the search filter for details.
- Get concepts with display names containing "electrodynamics":
https://api.openalex.org/concepts?filter=display_name.search:electrodynamics
In most cases, you should use the search parameter instead of this filter because it uses a better search algorithm.
Value: a Boolean (
true or false)Returns: concepts that have or lack a Wikidata ID, depending on the given value. For now, all concepts in OpenAlex do have Wikidata IDs.
Last modified 15d ago