Old OpenAlex API documentation
  • Overview
  • Quickstart tutorial
  • API Entities
    • Entities overview
    • 📄Works
      • Work object
        • Authorship object
        • Location object
      • Get a single work
      • Get lists of works
      • Filter works
      • Search works
      • Group works
      • Get N-grams
    • 👩Authors
      • Author object
      • Get a single author
      • Get lists of authors
      • Filter authors
      • Search authors
      • Group authors
      • Limitations
      • Author disambiguation
    • 📚Sources
      • Source object
      • Get a single source
      • Get lists of sources
      • Filter sources
      • Search sources
      • Group sources
    • 🏫Institutions
      • Institution object
      • Get a single institution
      • Get lists of institutions
      • Filter institutions
      • Search institutions
      • Group institutions
    • 💡Topics
      • Topic object
      • Get a single topic
      • Get lists of topics
      • Filter topics
      • Search topics
      • Group topics
    • 🗝️Keywords
    • 🏢Publishers
      • Publisher object
      • Get a single publisher
      • Get lists of publishers
      • Filter publishers
      • Search publishers
      • Group publishers
    • 💰Funders
      • Funder object
      • Get a single funder
      • Get lists of funders
      • Filter funders
      • Search funders
      • Group funders
    • 🌎Geo
      • Continents
      • Regions
    • 💡Concepts
      • Concept object
      • Get a single concept
      • Get lists of concepts
      • Filter concepts
      • Search concepts
      • Group concepts
    • Aboutness endpoint (/text)
  • How to use the API
    • API Overview
    • Get single entities
      • Random result
      • Select fields
    • Get lists of entities
      • Paging
      • Filter entity lists
      • Search entities
      • Sort entity lists
      • Select fields
      • Sample entity lists
      • Autocomplete entities
    • Get groups of entities
    • Rate limits and authentication
  • Download all data
    • OpenAlex snapshot
    • Snapshot data format
    • Download to your machine
    • Upload to your database
      • Load to a data warehouse
      • Load to a relational database
        • Postgres schema diagram
  • Additional Help
    • Tutorials
    • Report bugs
    • FAQ
Powered by GitBook
On this page
  • /works attribute filters
  • /works convenience filters
  1. API Entities
  2. Works

Filter works

PreviousGet lists of worksNextSearch works

Last updated 9 months ago

It's easy to filter works with the filter parameter:

  • Get works where the publication year is 2020

In this example the filter is publication_year and the value is 2020.

It's best to before trying these out. It will show you how to combine filters and build an AND, OR, or negation query.

/works attribute filters

You can filter using these attributes of the 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 and . 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.

  • (alias: author.id) — Authors for a work (OpenAlex ID)

  • (alias: author.orcid) — Authors for a work (ORCID)

  • (alias: institutions.country_code)

  • (alias: institutions.id) — Institutions affiliated with the authors of a work (OpenAlex ID)

  • (alias: institutions.ror) — Institutions affiliated with the authors of a work (ROR ID)

  • (alias: is_corresponding) — This filter marks whether or not we have corresponding author information for a given work

  • — The Open Acess license for a work

  • (alias: concept.id) — The concepts associated with a work

  • — Corresponding authors for a work (OpenAlex ID)

  • — The DOI (Digital Object Identifier) of a work

  • — Award IDs for grants

  • — Funding organizations linked to grants for a work

  • (alias: pmid)

  • (alias: openalex) — The OpenAlex ID for a work

  • (alias: mag)

  • (alias: is_oa) — Whether a work is Open Access

  • (alias: oa_status) — The Open Access status for a work (e.g., gold, green, hybrid, etc.)

/works convenience filters

abstract.search

Text search using abstracts

Value: a search string

authors_count

Number of authors for a work

Value: an Integer

authorships.institutions.continent (alias: institutions.continent)

Returns: works where at least one of the author's institutions is in the chosen continent.

authorships.institutions.is_global_south (alias: institutions.is_global_south)

Value: a Boolean (true or false)

best_open_version

Value: a String with one of the following values:

  • any: This means that best_oa_location.version = submittedVersion, acceptedVersion, or publishedVersion

  • acceptedOrPublished: This means that best_oa_location.version can be acceptedVersion or publishedVersion

  • published: This means that best_oa_location.version = publishedVersion

cited_by

cites

concepts_count

Value: an Integer

default.search

Text search across titles, abstracts, and full text of works

Value: a search string

display_name.search (alias: title.search)

Text search across titles for works

Value: a search string

from_created_date

Value: a date, formatted as yyyy-mm-dd

from_publication_date

Value: a date, formatted as yyyy-mm-dd

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.

from_updated_date

fulltext.search

Value: a search string

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.

has_abstract

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.

has_doi

Value: a Boolean (true or false)

has_oa_accepted_or_published_version

Value: a Boolean (true or false)

has_oa_submitted_version

Value: a Boolean (true or false)

has_orcid

Value: a Boolean (true or false)

has_pmcid

Value: a Boolean (true or false)

has_pmid

Value: a Boolean (true or false)

has_ngrams (DEPRECATED)

Works that have n-grams available to enable full-text search in OpenAlex.

Value: a Boolean (true or false)

has_references

Value: a Boolean (true or false)

journal

locations.source.host_institution_lineage

locations.source.publisher_lineage

mag_only

Value: a Boolean (true or false)

Returns: works which came from MAG (Microsoft Academic Graph), and no other data sources.

primary_location.source.has_issn

Value: a Boolean (true or false)

primary_location.source.publisher_lineage

raw_affiliation_strings.search

This filter used to be named raw_affiliation_string.search, but it is now raw_affiliation_strings.search (i.e., plural, with an 's').

Value: a search string

related_to

repository

You can also use this as a group_by to learn things about repositories:

title_and_abstract.search

Text search across titles and abstracts for works

Value: a search string

to_created_date

Value: a date, formatted as yyyy-mm-dd

to_publication_date

Value: a date, formatted as yyyy-mm-dd

to_updated_date

version

Value: a String with value publishedVersion, submittedVersion, acceptedVersion, or null

Want to filter by the display_name of an associated entity (author, institution, source, etc.)?

These filters aren't attributes of the object, but they're handy for solving some common use cases:

Returns: works whose abstract includes the given string. See the for details on the search algorithm used.

Get works with abstracts that mention "artificial intelligence":

Returns: works with the chosen number of objects (authors). You can use the inequality filter to select a range, such as authors_count:>5.

Get works that have exactly one author

Value: a String with a valid

Get works where at least one author's institution in each work is located in Europe

Returns: works where at least one of the author's institutions is in the Global South ().

Get works where at least one author's institution is in the Global South

Returns: works that meet the above criteria for .

Get works whose best_oa_location is a submitted, accepted, or published version: ``

Value: the for a given work

Returns: works found in the given work's section. You can think of this as outgoing citations.

Get works cited by :

Value: the for a given work

Returns: works that cite the given work. This is works that have the given OpenAlex ID in the section. You can think of this as incoming citations.

Get works that cite : ``

The number of results returned by this filter may be slightly higher than the work'sdue to a timing lag in updating that field.

Returns: works with the chosen number of .

Get works with at least three concepts assigned

This works the same as using the for Works.

Returns: works whose (title) includes the given string; see the for details.

Get works with titles that mention the word "wombat":

For most cases, you should use the parameter instead of this filter, because it uses a better search algorithm and searches over abstracts as well as titles.

Returns: works with greater than or equal to the given date.

This field requires an

Get works created on or after January 12th, 2023 (does not work without valid API key):

Returns: works with greater than or equal to the given date.

Get works published on or after March 14th, 2001:

Value: a date, formatted as an date or date-time string (for example: "2020-05-17", "2020-05-17T15:30", or "2020-01-02T00:22:35.180390").

Returns: works with greater than or equal to the given date.

This field requires an

Get works updated on or after January 12th, 2023 (does not work without valid API key):

Learn more about using this filter to get the freshest data possible with our .

Returns: works whose fulltext includes the given string. Fulltext search is available for a subset of works, obtained either from PDFs or , see for more details.

Get works with fulltext that mention "climate change":

Get the works that have abstracts:

Returns: works that have or lack a DOI, depending on the given value. It's especially useful for .

Get the works that have no DOI assigned: ``

Returns: works with at least one of the has = true and 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

Returns: works with at least one of the has = true and is submittedVersion. This is useful for finding works with preprints deposited somewhere.

Get works with an OA submitted copy: ``

Returns: if true it returns works where at least one author or has an . If false, it returns works where no authors have an ORCID ID. This is based on the orcid field within . Note that, sometimes, we assign ORCID using , 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:

Returns: works that have or lack a PubMed Central identifier () depending on the given value.

Get the works that have a pmcid: ``

Returns: works that have or lack a PubMed identifier (), depending on the given value.

Get the works that have a pmid: ``

This filter has been deprecated. See instead: .

Returns: works for which n-grams are available or unavailable, depending on the given value. N-grams power fulltext searches through the filter and the parameter.

Get the works that have n-grams:

Returns: works that have or lack , depending on the given value.

Get the works that have references:

Value: the for a given , where the source is

Returns: works where the chosen is the .

Value: the for an

Returns: works where the given institution ID is in

Get the works that have https://openalex.org/I205783295 in their host_organization_lineage:

Value: the for a

Returns: works where the given publisher ID is in

Get the works that have https://openalex.org/P4310320547 in their publisher_lineage:

MAG was a project by Microsoft Research to catalog all of the scholarly content on the internet. After it was discontinued in 2021, OpenAlex built upon the data MAG had accumulated, connecting and expanding it using . The methods that MAG used to identify and aggregate scholarly content were quite different from most of our other sources, and so the content inherited from MAG, especially works that we did not connect with data from other sources, can look different from other works. While it's great to have these MAG-only works available, you may not always want to include them in your results or analyses. This filter allows you to include or exclude any works that came from MAG and only MAG.

Get all MAG-only works:

Returns: works where the has at least one ISSN assigned.

Get the works that have an ISSN within the primary location:

Value: the for a

Returns: works where the given publisher ID is in

Get the works that have https://openalex.org/P4310320547 in their publisher_lineage:

Returns: works that have at least one which includes the given string. See the 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_strings:

Value: the for a given work

Returns: works found in the given work's section.

Get works related to :

Value: the for a given , where the source is

Returns: works where the chosen exists within the .

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)

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

Learn which repositories have the most open access works

Returns: works whose (title) or abstract includes the given string; see the for details.

Get works with title or abstract mentioning "gum disease":

Returns: works with less than or equal to the given date.

This field requires an

Get works created on or after January 12th, 2023 (does not work without valid API key):

Returns: works with less than or equal to the given date.

Get works published on or before March 14th, 2001:

Value: a date, formatted as an date or date-time string (for example: "2020-05-17", "2020-05-17T15:30", or "2020-01-02T00:22:35.180390").

Returns: works with less than or equal to the given date.

This field requires an

Get works updated before or on January 12th, 2023 (does not work without valid API key):

Returns: works where the chosen version exists within the . 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:

📄
👏
Work
search page
https://api.openalex.org/works?filter=abstract.search:artificial%20intelligence
https://api.openalex.org/works?filter=authors\_count:1
https://api.openalex.org/works?filter=authorships.institutions.continent:europe
https://api.openalex.org/works?filter=authorships.institutions.is\_global\_south:true
https://api.openalex.org/works?filter=best_open_version:any
https://openalex.org/W2766808518
https://api.openalex.org/works?filter=cited_by:W2766808518
https://openalex.org/W2741809807
https://api.openalex.org/works?filter=cites:W2741809807
https://api.openalex.org/works?filter=concepts\_count:>2
https://api.openalex.org/works?filter=title.search:wombat
OpenAlex Premium subscription to access. Click here to learn more.
https://api.openalex.org/works?filter=from_created_date:2023-01-12&api_key=myapikey
https://api.openalex.org/works?filter=from_publication_date:2001-03-14
ISO 8601
OpenAlex Premium subscription to access. Click here to learn more.
https://api.openalex.org/works?filter=from_updated_date:2023-01-12&api_key=myapikey
Premium How-To
https://api.openalex.org/works?filter=fulltext.search:climate%20change
https://api.openalex.org/works?filter=has_abstract:true
grouping
https://api.openalex.org/works?filter=has_doi:false
https://api.openalex.org/works?filter=has_oa_accepted_or_published_version:true
https://api.openalex.org/works?filter=has_oa_submitted_version:true
https://api.openalex.org/works?filter=has_orcid:true
https://api.openalex.org/works?filter=has_pmcid:true
https://api.openalex.org/works?filter=has_pmid:true
https://api.openalex.org/works?filter=has_ngrams:true
https://api.openalex.org/works?filter=has_references:true
https://api.openalex.org/works?filter=locations.source.host_institution_lineage:https://openalex.org/I205783295
https://api.openalex.org/works?filter=locations.source.publisher_lineage:https://openalex.org/P4310320547
a variety of other sources
https://api.openalex.org/works?filter=mag_only:true
https://api.openalex.org/works?filter=primary_location.source.has_issn:true
https://api.openalex.org/works?filter=primary_location.source.publisher_lineage:https://openalex.org/P4310320547
https://api.openalex.org/works?filter=raw_affiliation_strings.search:department%20of%20political%20science%20university%20of%amsterdam
https://openalex.org/W2486144666
https://api.openalex.org/works?filter=related_to:W2486144666
https://api.openalex.org/works?filter=repository:S4306400393
https://api.openalex.org/works?filter=institutions.id:I27837315,repository:!S4306400393
https://api.openalex.org/works?filter=is_oa:true&group_by=repository
https://api.openalex.org/works?filter=title_and_abstract.search:gum%20disease
OpenAlex Premium subscription to access. Click here to learn more.
https://api.openalex.org/works?filter=to_created_date:2024-01-12&api_key=myapikey
https://api.openalex.org/works?filter=to_publication_date:2001-03-14
ISO 8601
OpenAlex Premium subscription to access. Click here to learn more.
https://api.openalex.org/works?filter=to_updated_date:2023-01-12&api_key=myapikey
https://api.openalex.org/works?filter=version:publishedVersion
https://api.openalex.org/works?filter=publication\_year:2020
read about filters
Work
search page
n-grams
author disambiguation
source
Institution
Publisher
Publisher
search page
source
search page
fulltext.search
See here.
search parameter
search
search
OpenAlex ID
OpenAlex ID
OpenAlex ID
OpenAlex ID
OpenAlex ID
OpenAlex ID
OpenAlex ID
OpenAlex ID
raw_affiliation_strings
read more
continent filter
authorships.affiliations.institution_ids
authorships.author.id
authorships.author.orcid
authorships.countries
authorships.institutions.country_code
authorships.institutions.id
authorships.institutions.lineage
authorships.institutions.ror
authorships.institutions.type
authorships.is_corresponding
authorships.author
is_oa
is_oa
type: journal
locations.source.host_organization_lineage
locations.source.host_organization_lineage
primary_location.source.host_organization_lineage
type: repository
source ID
source ID
primary_location
locations
apc_list.value
apc_list.currency
apc_list.provenance
apc_list.value_usd
apc_paid.value
apc_paid.currency
apc_paid.provenance
apc_paid.value_usd
best_oa_location.is_accepted
best_oa_location.is_published
best_oa_location.license
best_oa_location.source.id
best_oa_location.source.is_in_doaj
best_oa_location.source.issn
best_oa_location.source.host_organization
best_oa_location.source.type
best_oa_location.version
biblio.first_page
biblio.issue
biblio.last_page
biblio.volume
cited_by_count
concepts.id
concepts.wikidata
corresponding_author_ids
corresponding_institution_ids
countries_distinct_count
doi
fulltext_origin
fwci
grants.award_id
grants.funder
has_fulltext
ids.pmcid
ids.pmid
ids.openalex
ids.mag
indexed_in
institutions_distinct_count
is_paratext
is_retracted
keywords.keyword
language
locations.is_accepted
locations.is_oa
locations.is_published
locations.license
locations.source.id
locations.source.is_core
locations.source.is_in_doaj
locations.source.issn
locations.source.host_organization
locations.source.type
locations.version
locations_count
open_access.any_repository_has_fulltext
open_access.is_oa
open_access.oa_status
primary_location.is_accepted
primary_location.is_oa
primary_location.is_published
primary_location.license
primary_location.source.id
primary_location.source.is_core
primary_location.source.is_in_doaj
primary_location.source.issn
primary_location.source.host_organization
primary_location.source.type
primary_location.version
primary_topic.id
primary_topic.domain.id
primary_topic.field.id
primary_topic.subfield.id
publication_year
publication_date
sustainable_development_goals.id
topics.id
topics.domain.id
topics.field.id
topics.subfield.id
type
type_crossref
authorships
best_oa_location
referenced_works
referenced_works
cited_by_count
concepts
display_name
created_date
publication_date
updated_date
Work.has_fulltext
locations
version
locations
version
ORCID ID
pmcid
pmid
has_fulltext
referenced_works
primary_location.source
primary_location
related_works
locations
display_name
created_date
publication_date
updated_date
locations