Comment on page
Filter works
It's easy to filter works with the
filter parameter:- Get works where the publication year is 2020
https://api.openalex.org/works?filter=publication\_year:2020
In this example the filter is
publication_year and the value is 2020.It's best to read about filters before trying these out. It will show you how to combine filters and build an AND, OR, or negation query.
You can filter using these attributes of the
Work object (click each one to view their documentation on the Work object page):The
host_venue and alternate_host_venues properties have been deprecated in favor of primary_location and locations. The attributes host_venue and alternate_host_venues are no longer available in the Work object, and trying to access them in filters or group-bys will return an error.-
authorships.institutions.id(alias:institutions.id) — Institutions affiliated with the authors of a work (OpenAlex ID) -
authorships.institutions.ror(alias:institutions.ror) — Institutions affiliated with the authors of a work (ROR ID) -
authorships.is_corresponding(alias:is_corresponding) — This filter marks whether or not we have corresponding author information for a given work -
open_access.oa_status(alias:oa_status) — The Open Access status for a work (e.g., gold, green, hybrid, etc.)
Want to filter by the
display_name of an associated entity (author, institution, source, etc.)? See here.These filters aren't attributes of the
Work object, but they're handy for solving some common use cases:Text search using abstracts
Value: a search string
Returns: works whose abstract includes the given string. See the search page 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
Number of authors for a work
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.Returns: works where at least one of the author's institutions is in the chosen continent.
- 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
Value: a String with one of the following values:
any: This means thatbest_oa_location.version=submittedVersion,acceptedVersion, orpublishedVersionacceptedOrPublished: This means thatbest_oa_location.versioncan beacceptedVersionorpublishedVersionpublished: This means thatbest_oa_location.version=publishedVersion
- Get works whose
best_oa_locationis a submitted, accepted, or published version:https://api.openalex.org/works?filter=best_open_version:any``
Returns: works found in the given work's
referenced_works section. You can think of this as outgoing citations.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.Value: an Integer
- Get works with at least three concepts assigned
https://api.openalex.org/works?filter=concepts\_count:>2
Text search across titles, abstracts, and full text of works
Value: a search string
Text search across titles for works
Value: a search string
Returns: works whose
display_name (title) includes the given string; see the search page 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 date, formatted as
yyyy-mm-dd- Get works created on or after January 12th, 2023 (does not work without valid API key):
https://api.openalex.org/works?filter=from_created_date:2023-01-12&api_key=myapikey``
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
Filtering by publication date is not a reliable way to retrieve recently updated and created works, due to the way publishers assign publication dates. Use
from_created_date or from_updated_date to get the latest changes in OpenAlex.Value: a date, formatted as an ISO 8601 date or date-time string (for example: "2020-05-17", "2020-05-17T15:30", or "2020-01-02T00:22:35.180390").
- Get works updated on or after January 12th, 2023 (does not work without valid API key):
https://api.openalex.org/works?filter=from_updated_date:2023-01-12&api_key=myapikey
Value: a search string
Returns: works whose fulltext includes the given string. Fulltext search is available for a subset of works, obtained either from PDFs or n-grams, see
Work.has_fulltext for more details.- Get works with fulltext that mention "climate change":
https://api.openalex.org/works?filter=fulltext.search:climate%20change``
We combined some n-grams before storing them in our search database, so querying for an exact phrase using quotes does not always work well.
Works that have an abstract available
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: works with at least one of the
locations has 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)- Get works with an OA submitted copy:
https://api.openalex.org/works?filter=has_oa_submitted_version:true``
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. Note that, sometimes, we assign ORCID using author disambiguation, so this does not necessarily mean that the work itself has ORCID information.- 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)Works that have n-grams available to enable full-text search in OpenAlex.
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)- Get the works that have
https://openalex.org/I205783295in theirhost_organization_lineage:https://api.openalex.org/works?filter=locations.source.host_institution_lineage:https://openalex.org/I205783295
- Get the works that have
https://openalex.org/P4310320547in theirpublisher_lineage:https://api.openalex.org/works?filter=locations.source.publisher_lineage:https://openalex.org/P4310320547
Value: a Boolean (
true or false)- Get the works that have an ISSN within the primary location:
https://api.openalex.org/works?filter=primary_location.source.has_issn:true
Returns: works where the given publisher ID is in
primary_location.source.host_organization_lineage- Get the works that have
https://openalex.org/P4310320547in theirpublisher_lineage:https://api.openalex.org/works?filter=primary_location.source.publisher_lineage:https://openalex.org/P4310320547
Value: a search string
Returns: works that have at least one
raw_affiliation_string which includes the given string. See the search page 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``
- Get works related to https://openalex.org/W2486144666:
https://api.openalex.org/works?filter=related_to:W2486144666
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/S4306400393)https://api.openalex.org/works?filter=repository:S4306400393 - 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:!S4306400393
You can also use this as a
group_by to learn things about repositories:- Learn which repositories have the most open access works
https://api.openalex.org/works?filter=is_oa:true&group_by=repository
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 String with value
publishedVersion, submittedVersion, acceptedVersion, or nullReturns: works where the chosen version exists within the
locations. If null, it returns works where no version is found in any of the locations.- Get works where a published version is available in at least one of the locations:
[`https://api.openalex.org/works?filter=version:publishedVersion`](https://api.openalex.org/works?filter=version:publishedVersion)
Last modified 3d ago