There's a lot of useful data inside a work. When you use the API to get a single work or lists of works, this is what's returned.

abstract_inverted_index

Object: The abstract of the work, as an inverted index, which encodes information about the abstract's words and their positions within the text. Like Microsoft Academic Graph, OpenAlex doesn't include plaintext abstracts due to legal constraints.

abstract_inverted_index: {
    Despite: [
        0
    ],
    growing: [
        1
    ],
    interest: [
        2
    ],
    in: [
        3,
        57,
        73,
        110,
        122
    ],
    Open: [
        4,
        201
    ],
    Access: [
        5
    ],
    ...
}

Abstract inverted index coverage

Newer works are more likely to have an abstract inverted index. For example, over 60% of works in 2022 have abstract data, compared to 45% for works older than 2000. Full chart is below:

alternate_host_venues (deprecated)

authorships

List: List of Authorship objects, each representing an author and their institution. Limited to the first 100 authors to maintain API performance.

For more information, see the Authorship object page.

authorships: [
    // first authorship object:
    {
        author_position: "middle",
        author: {
            id: "https://openalex.org/A5023888391",
            display_name: "Jason Priem",
            orcid: "https://orcid.org/0000-0001-6187-6610"
        },
        institutions: [
            {
                id: "https://openalex.org/I4200000001",
                display_name: "OurResearch",
                ror: "https://ror.org/02nr0ka47",
                country_code: "US",
                type: "nonprofit"
            }
        ],
        // other fields removed for brevity. See the Authorship object documentation
    },
    
    // more authorship objects go here
]

apc_list

Object: Information about this work's APC (article processing charge). The object contains:

• value: Integer

• currency: String

• provenance: String — the source of this data. Currently the only value is “doaj” (DOAJ)

• value_usd: Integer — the APC converted into USD

This value is the APC list price–the price as listed by the journal’s publisher. That’s not always the price actually paid, because publishers may offer various discounts to authors. Unfortunately we don’t always know this discounted price, but when we do you can find it in apc_paid.

Currently our only source for this data is DOAJ, and so doaj is the only value for apc_list.provenance, but we’ll add other sources over time.

We currently don’t have information on the list price for hybrid journals (toll-access journals that also provide an open-access option), but we will add this at some point. We do have apc_paid information for hybrid OA works occasionally.

You can use this attribute to find works published in Diamond open access journals by looking at works where apc_list.value is zero. See open_access.oa_status for more info.

apc_payment: {
    value: 3200,
    currency: "USD",
    value_usd: 3200,
    provenance: "doaj"
}

apc_paid

Object: Information about the paid APC (article processing charge) for this work. The object contains:

• value: Integer

• currency: String

• provenance: String — currently either openapc or doaj, but more will be added; see below for details.

• value_usd: Integer — the APC converted into USD

You can find the listed APC price (when we know it) for a given work using apc_list. However, authors don’t always pay the listed price; often they get a discounted price from publishers. So it’s useful to know the APC actually paid by authors, as distinct from the list price. This is our effort to provide this.

Our best source for the actually paid price is the OpenAPC project. Where available, we use that data, and so apc_paid.provenance is openapc. Where OpenAPC data is unavailable (and unfortunately this is common) we make our best guess by assuming the author paid the APC list price, and apc_paid.provenance will be set to wherever we got the list price from.

apc_payment: {
    value: 2250,
    currency: "EUR",
    value_usd: 2426,
    provenance: "openapc"
}

best_oa_location

Object: A Location object with the best available open access location for this work.

We score open locations to determine which is best using these factors:

1. Must have is_oa: true

2. type_:_ "publisher" is better than "repository".

3. version: "publishedVersion" is better than "acceptedVersion", which is better than "submittedVersion".

4. pdf_url: A location with a direct PDF link is better than one without.

5. repository rankings: Some major repositories like PubMed Central and arXiv are ranked above others.

best_oa_location: {
  is_oa: true,
  landing_page_url: "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1398957",
  pdf_url: null,
  source: {
    id: "https://openalex.org/S2764455111",
    display_name: "PubMed Central",
    issn_l: null,
    issn: null,
    host_organization: "https://openalex.org/I1299303238",
    type: "repository"
  },
  license: null,
  version: "publishedVersion"
}

biblio

Object: Old-timey bibliographic info for this work. This is mostly useful only in citation/reference contexts. These are all strings because sometimes you'll get fun values like "Spring" and "Inside cover."

• volume (String)

• issue (String)

• first_page (String)

• last_page (String)

biblio: {
    volume: "495",
    issue: "7442",
    first_page: "437",
    last_page: "440"
}

citation_normalized_percentile

Object: The percentile of this work's citation count normalized by work type, publication year, and subfield. This field represents the same information as the FWCI expressed as a percentile. Learn more in the reference article: Field Weighted Citation Impact (FWCI).

citation_normalized_percentile: {
        value: 0.999948,
        is_in_top_1_percent: true,
        is_in_top_10_percent": true
}

cited_by_api_url

String: A URL that uses the cites filter to display a list of works that cite this work. This is a way to expand cited_by_count into an actual list of works.

cited_by_count

Integer: The number of citations to this work. These are the times that other works have cited this work: Other works ➞ This work.

cited_by_count: 382

concepts

List: List of dehydrated Concept objects.

Each Concept object in the list also has one additional property:

• score (Float): The strength of the connection between the work and this concept (higher is stronger). This number is produced by AWS Sagemaker, in the last layer of the machine learning model that assigns concepts.

Concepts with a score of at least 0.3 are assigned to the work. However, ancestors of an assigned concept are also added to the work, even if the ancestor scores are below 0.3.

concepts: [
    {
        id: "https://openalex.org/C71924100",
        wikidata: "https://www.wikidata.org/wiki/Q11190",
        display_name: "Medicine",
        level: 0,
        score: 0.9187037
    },
    {
        id: "https://openalex.org/C3007834351",
        wikidata: "https://www.wikidata.org/wiki/Q82069695",
        display_name: "Severe acute respiratory syndrome coronavirus 2 (SARS-CoV-2)",
        level: 5,
        score: 0.8070164
    },
    ...
    {
        id: "https://openalex.org/C191935318",
        wikidata: "https://www.wikidata.org/wiki/Q148",
        display_name: "China",
        level: 2,
        score: 0.5948172
    },
    ...
    {
        id: "https://openalex.org/C121608353",
        wikidata: "https://www.wikidata.org/wiki/Q12078",
        display_name: "Cancer",
        level: 2,
        score: 0.46887803
    },
    ...
    {
        id: "https://openalex.org/C17744445",
        wikidata: "https://www.wikidata.org/wiki/Q36442",
        display_name: "Political science",
        level: 0,
        score: 0
    }
]

corresponding_author_ids

List: OpenAlex IDs of any authors for which authorships.is_corresponding is true.

corresponding_author_ids: ["https://openalex.org/A5004365451"]

corresponding_institution_ids

List: OpenAlex IDs of any institutions found within an authorship for which authorships.is_corresponding is true.

corresponding_institution_ids: ["https://openalex.org/I4210123613"]

countries_distinct_count

Integer: Number of distinct country_codes among the authorships for this work.

countries_distinct_count: 4

counts_by_year

List: Works.cited_by_count for each of the last ten years, binned by year. To put it another way: each year, you can see how many times this work was cited.

Any citations older than ten years old aren't included. Years with zero citations have been removed so you will need to add those in if you need them.

counts_by_year: [
    {
        year: 2022,
        cited_by_count: 8
    },
    {
        year: 2021,
        cited_by_count: 252
    },
    ...
    {
        year: 2012,
        cited_by_count: 79
    }
]

created_date

String: The date this Work object was created in the OpenAlex dataset, expressed as an ISO 8601 date string.

created_date: "2017-08-08"

display_name

String: Exactly the same as Work.title. It's useful for Works to include a display_name property, since all the other entities have one.

display_name: "The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles",

doi

String: The DOI for the work. This is the Canonical External ID for works.

Occasionally, a work has more than one DOI--for example, there might be one DOI for a preprint version hosted on bioRxiv, and another DOI for the published version. However, this field always has just one DOI, the DOI for the published work.

doi: "https://doi.org/10.7717/peerj.4375"

fulltext_origin

String: If a work's full text is searchable in OpenAlex (has_fulltext is true), this tells you how we got the text. This will be one of:

• pdf: We used Grobid to get the text from an open-access PDF.

• ngrams: Full text search is enabled using N-grams obtained from the Internet Archive.

This attribute is only available for works with has_fulltext:true.

fulltext_origin: "pdf"

fwci

Float: The Field-weighted Citation Impact (FWCI), calculated for a work as the ratio of citations received / citations expected in the year of publications and three following years. Learn more in the reference article: Field Weighted Citation Impact (FWCI).

fwci: 76.992

grants

List: List of grant objects, which include the Funder and the award ID, if available. Our grants data comes from Crossref, and is currently fairly limited.

grants: [
    // grant for which we have the grant details:
    {
        funder: "https://openalex.org/F4320306076",
        funder_display_name: "National Science Foundation",
        award_id: "ABI 1661218",
    },
    // grant for which we do not have the details:
    {
        funder: "https://openalex.org/F4320306084",
        funder_display_name: "U.S. Department of Energy",
        award_id: null,
    },
]

has_fulltext

Boolean: Set to true if the work's full text is searchable in OpenAlex. This does not necessarily mean that the full text is available to you, dear reader; rather, it means that we have indexed the full text and can use it to help power searches. If you are trying to find the full text for yourself, try looking in open_access.oa_url.

We get access to the full text in one of two ways: either using an open-access PDF, or using N-grams obtained from the Internet Archive. You can learn where a work's full text came from at fulltext_origin.

has_fulltext: true

host_venue (deprecated)

id

String: The OpenAlex ID for this work.

id: "https://openalex.org/W2741809807"

ids

Object: All the external identifiers that we know about for this work. IDs are expressed as URIs whenever possible. Possible ID types:

• doi (String: The DOI. Same as Work.doi)

• mag (Integer: the Microsoft Academic Graph ID)

• openalex (String: The OpenAlex ID. Same as Work.id)

• pmid (String: The Pubmed Identifier)

• pmcid (String: the Pubmed Central identifier)

ids: {
    openalex: "https://openalex.org/W2741809807",
    doi: "https://doi.org/10.7717/peerj.4375",
    mag: 2741809807,
    pmid: "https://pubmed.ncbi.nlm.nih.gov/29456894"
}

indexed_in

List: The sources this work is indexed in. Possible values: arxiv, crossref, doaj, pubmed.

indexed_in: [
    "arxiv", "crossref", "pubmed"
] 

institutions_distinct_count

Integer: Number of distinct institutions among the authorships for this work.

institutions_distinct_count: 4

is_paratext

Boolean: True if we think this work is paratext.

In our context, paratext is stuff that's in a scholarly venue (like a journal) but is about the venue rather than a scholarly work properly speaking. Some examples and nonexamples:

• yep it's paratext: front cover, back cover, table of contents, editorial board listing, issue information, masthead.

• no, not paratext: research paper, dataset, letters to the editor, figures

Turns out there is a lot of paratext in registries like Crossref. That's not a bad thing... but we've found that it's good to have a way to filter it out.

We determine is_paratext algorithmically using title heuristics.

is_paratext: false 

is_retracted

Boolean: True if we know this work has been retracted.

We identify works that have been retracted using the public Retraction Watch database, a public resource made possible by a partnership between Crossref and The Center for Scientific Integrity.

is_retracted: false 

keywords

List of objects: Short phrases identified based on works' Topics. For background on how Keywords are identified, see the Keywords page at OpenAlex help pages.

The score for each keyword represents the similarity score of that keyword to the title and abstract text of the work.

We provide up to 5 keywords per work, for all keywords with scores above a certain threshold.

[
    {
        id: "https://openalex.org/keywords/global-seaweed-distribution",
        display_name: "Global Seaweed Distribution",
        score: 0.559386
    },
    {
        id: "https://openalex.org/keywords/climate-change-impacts",
        display_name: "Climate Change Impacts",
        score: 0.535795
    },
    {
        id: "https://openalex.org/keywords/ecosystem-resilience",
        display_name: "Ecosystem Resilience",
        score: 0.502789
    }
]

language

String: The language of the work in ISO 639-1 format. The language is automatically detected using the information we have about the work. We use the langdetect software library on the words in the work's abstract, or the title if we do not have the abstract. The source code for this procedure is here. Keep in mind that this method is not perfect, and that in some cases the language of the title or abstract could be different from the body of the work.

A few things to keep in mind about this:

• We don't always assign a language if we do not have enough words available to accurately guess.

• We report the language of the metadata, not the full text. For example, if a work is in French, but the title and abstract are in English, we report the language as English.

• In some cases, abstracts are in two different languages. Unfortunately, when this happens, what we report will not be accurate.

language: "en"

license

String: The license applied to this work at this host. Most toll-access works don't have an explicit license (they're under "all rights reserved" copyright), so this field generally has content only if is_oa is true.

license: "cc-by"

locations

List: A list of Location objects describing all unique places where this work lives.

locations: [ 
  {
    is_oa: true,
    landing_page_url: "https://doi.org/10.1073/pnas.17.6.401",
    pdf_url: "http://www.pnas.org/content/17/6/401.full.pdf",
    source: {
      id: "https://openalex.org/S125754415",
      display_name: "Proceedings of the National Academy of Sciences of the United States of America",
      issn_l: "0027-8424",
      issn: ["1091-6490", "0027-8424"],
      host_organization: "https://openalex.org/P4310320052",
      type: "journal"
    },
    license: null,
    version: "publishedVersion"
  },
  {
    is_oa: true,
    landing_page_url: "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1076072",
    pdf_url: null,
    source: {
      id: "https://openalex.org/S2764455111",
      display_name: "PubMed Central",
      issn_l: null,
      issn: null,
      host_organization: "https://openalex.org/I1299303238",
      type: "repository"
    },
    license: null,
    version: "publishedVersion"
  }
]

locations_count

Integer: Number of locations for this work.

locations_count: 3

mesh

List: List of MeSH tag objects. Only works found in PubMed have MeSH tags; for all other works, this is an empty list.

mesh: [
    {
        descriptor_ui: "D017712",
        descriptor_name: "Peer Review, Research",
        qualifier_ui: "Q000379",
        qualifier_name: "methods",
        is_major_topic: false
    },
    {
        descriptor_ui: "D017712",
        descriptor_name: "Peer Review, Research",
        qualifier_ui: "Q000592",
        qualifier_name: "standards",
        is_major_topic: true
    }
]

open_access

Object: Information about the access status of this work, as an OpenAccess object.

open_access: {
    is_oa: true,
    oa_status: "gold",
    oa_url: "https://peerj.com/articles/4375.pdf",
    any_repository_has_fulltext: true
},

primary_location

Object: A Location object with the primary location of this work.

The primary_location is where you can find the best (closest to the version of record) copy of this work. For a peer-reviewed journal article, this would be a full text published version, hosted by the publisher at the article's DOI URL.

primary_location: {
  is_oa: true,
  landing_page_url: "https://doi.org/10.1073/pnas.17.6.401",
  pdf_url: "http://www.pnas.org/content/17/6/401.full.pdf",
  source: {
    id: "https://openalex.org/S125754415",
    display_name: "Proceedings of the National Academy of Sciences of the United States of America",
    issn_l: "0027-8424",
    issn: ["1091-6490", "0027-8424"],
    host_organization: "https://openalex.org/P4310320052",
    type: "journal"
  },
  license: null,
  version: "publishedVersion"
}

primary_topic

Object

The top ranked Topic for this work. This is the same as the first item in Work.topics.

primary_topic: {
    id: "https://openalex.org/T12419",
    display_name: "Analysis of Cardiac and Respiratory Sounds",
    score: 	0.9997,
    subfield: {
        id: 2740,
        display_name: "Pulmonary and Respiratory Medicine"
    }
    field: {
        id: 27,
        display_name: "Medicine"
    }
    domain: {
        id: 4,
        display_name: "Health Sciences"
    }
}

publication_date

String: The day when this work was published, formatted as an ISO 8601 date.

Where different publication dates exist, we usually select the earliest available date of electronic publication.

This date applies to the version found at Work.url. The other versions, found in Work.locations, may have been published at different (earlier) dates.

publication_date: "2018-02-13"

publication_year

Integer: The year this work was published.

This year applies to the version found at Work.url. The other versions, found in Work.locations, may have been published in different (earlier) years.

publication_year: 2018

referenced_works

List: OpenAlex IDs for works that this work cites. These are citations that go from this work out to another work: This work ➞ Other works.

referenced_works: [
    "https://openalex.org/W2753353163",
    "https://openalex.org/W2785823074",
    "https://openalex.org/W2511661767",
    "https://openalex.org/W2115339903",
    "https://openalex.org/W2031754690"
]

related_works

List: OpenAlex IDs for works related to this work. Related works are computed algorithmically; the algorithm finds recent papers with the most concepts in common with the current paper.

related_works: [
    "https://openalex.org/W2753353163",
    "https://openalex.org/W2785823074",
    "https://openalex.org/W2511661767",
    "https://openalex.org/W2115339903",
    "https://openalex.org/W2031754690",
]

sustainable_development_goals

List: List of objects

The United Nations' 17 Sustainable Development Goals are a collection of goals at the heart of a global "shared blueprint for peace and prosperity for people and the planet." We use a machine learning model to tag works with their relevance to these goals based on our OpenAlex SDG Classifier, an mBERT machine learning model developed by the Aurora Universities Network. The score represents the model's predicted probability of the work's relevance for a particular goal.

We display all of the SDGs with a prediction score higher than 0.4.

sustainable_development_goals: [
    {
        id: "https://metadata.un.org/sdg/3",
        display_name: "Good health and well-being",
        score: 	0.95
    }
]

topics

List: List of objects

The top ranked Topics for this work. We provide up to 3 topics per work.

topics: [
    {
        id: "https://openalex.org/T12419",
        display_name: "Analysis of Cardiac and Respiratory Sounds",
        score: 	0.9997,
        subfield: {
            id: 2740,
            display_name: "Pulmonary and Respiratory Medicine"
        }
        field: {
            id: 27,
            display_name: "Medicine"
        }
        domain: {
            id: 4,
            display_name: "Health Sciences"
        }
    }
    ...
]

title

String: The title of this work.

This is exactly the same as Work.display_name. We include both attributes with the same information because we want all entities to have a display_name, but there's a longstanding tradition of calling this the "title," so we figured you'll be expecting works to have it as a property.

title: "The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles",

type

String: The type of the work.

You can see all of the different types along with their counts in the OpenAlex API here: https://api.openalex.org/works?group_by=type.

Most works are type article. This includes what was formerly (and currently in type_crossref) labeled as journal-article, proceedings-article, and posted-content. We consider all of these to be article type works, and the distinctions between them to be more about where they are published or hosted:

• Journal articles will have a primary_location.source.type of journal

• Conference proceedings will have a primary_location.source.type of conference

• Preprints or "posted content" will have a primary_location.version of submittedVersion

(Note that distinguishing between journals and conferences is a hard problem, one we often get wrong. We are working on improving this, but we also point out that the two have a lot of overlap in terms of their roles as hosts of research publications.)

Works that are hosted primarily on a preprint, or that are identified speicifically as preprints in the metadata we receive, are assigned the type preprint rather than article.

Works that represent stuff that is about the venue (such as a journal)—rather than a scholarly work properly speaking—have type paratext. These include things like front-covers, back-covers, tables of contents, and the journal itself (e.g., https://openalex.org/W4232230324).

We also have types for letter , editorial , erratum (corrections), libguides , supplementary-materials , and review (currently, articles that come from journals that exclusively publish review articles). Coverage is low on these but will improve.

Other work types follow the Crossref "type" controlled vocabulary—see type_crossref.

type: "article"

type_crossref

String: Legacy type information, using Crossref's "type" controlled vocabulary.

These are the work types that we used to use, before switching to our current system (see type).

You can see all possible values of Crossref's "type" controlled vocabulary via the Crossref api here: https://api.crossref.org/types.

Where possible, we just pass along Crossref's type value for each work. When that's impossible (eg the work isn't in Crossref), we do our best to figure out the type ourselves.

type_crossref: "journal-article"

updated_date

String: The last time anything in this Work object changed, expressed as an ISO 8601 date string (in UTC). This date is updated for any change at all, including increases in various counts.

updated_date: "2022-01-02T00:22:35.180390"

The OpenAccess object

The OpenAccess object describes access options for a given work. It's only found as part of the Work object.

any_repository_has_fulltext

Boolean: True if any of this work's locations has location.is_oa=true and location.source.type=repository.

Use case: researchers want to track Green OA, using a definition of "any repository hosts this." OpenAlex's definition (as used in oa_status) doesn't support this, because as soon as there's a publisher-hosted copy (bronze, hybrid, or gold), oa_status is set to that publisher-hosted status.

So there's a lot of repository-hosted content that the oa_status can't tell you about. Our State of OA paper calls this "shadowed Green." This feature makes it possible to track shadowed Green.

any_repository_has_fulltext: true

is_oa

Boolean: True if this work is Open Access (OA).

There are many ways to define OA. OpenAlex uses a broad definition: having a URL where you can read the fulltext of this work without needing to pay money or log in. You can use the locations and oa_status fields to narrow your results further, accommodating any definition of OA you like.

is_oa: true

oa_status

String: The Open Access (OA) status of this work. Possible values are:

• diamond: Published in a fully OA journal—one that is indexed by the DOAJ or that we have determined to be OA—with no article processing charges (i.e., free for both readers and authors).

• gold: Published in a fully OA journal.

• green: Toll-access on the publisher landing page, but there is a free copy in an OA repository.

• hybrid: Free under an open license in a toll-access journal.

• bronze: Free to read on the publisher landing page, but without any identifiable license.

• closed: All other articles.

oa_status: "gold"

oa_url

String: The best Open Access (OA) URL for this work.

Although there are many ways to define OA, in this context an OA URL is one where you can read the fulltext of this work without needing to pay money or log in. The "best" such URL is the one closest to the version of record.

This URL might be a direct link to a PDF, or it might be to a landing page that links to the free PDF

oa_url: "https://peerj.com/articles/4375.pdf"

1. Find the institution

You can use the institutions endpoint to learn about universities and research centers. OpenAlex has a powerful search feature that searches across 108,000 institutions.

Lets use it to search for Stanford University:

• Find Stanford University https://api.openalex.org/institutions?search=stanford

Our first result looks correct (yeah!):

{
  "id": "https://openalex.org/I97018004",
  "ror": "https://ror.org/00f54p054",
  "display_name": "Stanford University",
  "country_code": "US",
  "type": "education",
  "homepage_url": "http://www.stanford.edu/"
  // other fields removed
}

We can use the ID https://openalex.org/I97018004 in that result to find out more.

2. Find articles (works) associated with Stanford University

• Show works where at least one author is associated with Stanford University https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004

This is just one of the 50+ ways that you can filter works!

3. Filter works by publication year

Right now the list shows records for all years. Lets narrow it down to works that were published between 2010 to 2020, and sort from newest to oldest.

• Show works with publication years 2010 to 2020, associated with Stanford University https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004,publication_year:2010-2020&sort=publication_date:desc

4. Group works by publication year to show counts by year

Finally, you can group our result by publication year to get our final result, which is the number of articles produced by Stanford, by year from 2010 to 2020. There are more than 30 ways to group records in OpenAlex, including by publisher, journal, and open access status.

• Group records by publication year https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004,publication\_year:2010-2020\&group-by=publication\_year

That gives a result like this:

[
  {
    "key": "2020",
    "key_display_name": "2020",
    "count": 18627
  },
  {
    "key": "2019",
    "key_display_name": "2019",
    "count": 15933
  },
  {
    "key": "2017",
    "key_display_name": "2017",
    "count": 14789
  },
  ...
]

What's next?

Jump into an area of OpenAlex that interests you:

• Works

• Authors

• Sources

• Institutions

• Topics

• Publishers

• Funders

And check out our tutorials page for some hands-on examples!

Data

Access

Why OpenAlex?

OpenAlex is:

• Big — We have about twice the coverage of the other services, and have significantly better coverage of non-English works and works from the Global South.

• Easy — Our service is fast, modern, and well-documented.

• Open — Our complete dataset is free under the CC0 license, which allows for transparency and reuse.

Contact

Citation

Priem, J., Piwowar, H., & Orr, R. (2022). OpenAlex: A fully-open index of scholarly works, authors, venues, institutions, and concepts. ArXiv. https://arxiv.org/abs/2205.01833

Learn more about the OpenAlex entities:

The Location object describes the location of a given work. It's only found as part of the Work object.

There are three places in the Work object where you can find locations:

is_accepted

is_oa

Boolean: True if an Open Access (OA) version of this work is available at this location.

is_published

landing_page_url

String: The landing page URL for this location.

license

source

The concept of a source is meant to capture a certain social relationship between the host organization and a version of a work. When an organization puts the work on the internet, there is an understanding that they have, at some level, endorsed the work. This level varies, and can be very different depending on the source!

pdf_url

String: A URL where you can find this location as a PDF.

version

• publishedVersion: The document’s version of record. This is the most authoritative version.

• acceptedVersion: The document after having completed peer review and being officially accepted for publication. It will lack publisher formatting, but the content should be interchangeable with the that of the publishedVersion.

• submittedVersion: the document as submitted to the publisher by the authors, but before peer-review. Its content may differ significantly from that of the accepted article.

It's easy to get a work from from the API with: /works/<entity_id> Here's an example:

External IDs

You can look up works using external IDs such as a DOI:

You can use the full ID or a shorter Uniform Resource Name (URN) format like so:

Available external IDs for works are:

Select fields

affiliations

List: List of objects

author

author_position

String: A summarized description of this author's position in the work's author list. Possible values are first, middle, and last.

It's not strictly necessary, because author order is already implicitly recorded by the list order of Authorship objects; however it's useful in some contexts to have this as a categorical value.

countries

List: The country or countries for this author.

We determine the countries using a combination of matched institutions and parsing of the raw affiliation strings, so we can have this information for some authors even if we do not have a specific institutional affiliation.

institutions

is_corresponding

Boolean: If true, this is a corresponding author for this work.

raw_affiliation_strings

List: This author's affiliation as it originally came to us (on a webpage or in an API), as a list of raw unformatted strings. If there is only one affiliation, it will be a list of length one.

raw_author_name

String: This author's name as it originally came to us (on a webpage or in an API), as a raw unformatted string.

You can get lists of works:

Which returns a response like this:

Page and sort works

Sample works

Select fields

Works are scholarly documents like journal articles, books, datasets, and theses. OpenAlex indexes over 240M works, with about 50,000 added daily. You can access a work in the OpenAlex API like this:

• Get a list of OpenAlex works: https://api.openalex.org/works

That will return a list of Work object, describing everything OpenAlex knows about each work. We collect new works from many sources, including Crossref, PubMed, institutional and discipline-specific repositories (eg, arXiv). Many older works come from the now-defunct Microsoft Academic Graph (MAG).

Works are linked to other works via the referenced_works (outgoing citations), cited_by_api_url (incoming citations), and related_works properties.

What's next

Learn more about what you can do with works:

• The Work object

• Get a single work

• Get lists of works

• Filter works

• Search for works

• Group works

• Get N-grams

Authors are people who create works. You can get an author from the API like this:

• Get a list of OpenAlex authors: https://api.openalex.org/authors

The Canonical External ID for authors is ORCID; only a small percentage of authors have one, but the percentage is higher for more recent works.

Our information about authors comes from MAG, Crossref, PubMed, ORCID, and publisher websites, among other sources. To learn more about how we combine this information to get OpenAlex Authors, see Author Disambiguation.

Authors are linked to works via the works.authorships property.

What's next

Learn more about what you can with authors:

• The Author object

• Get a single author

• Get lists of authors

• Filter authors

• Search authors

• Group authors

Note that while n-grams are derived from the fulltext of a Work, the presence of n-grams for a given Work doesn't imply that the fulltext is available to you, the reader. It only means the fulltext was available to Internet Archive for indexing. Work.open_access is the place to go for information on public fulltext availability.

API Endpoint

Fulltext Coverage

You can see which works we have full-text for using the has_fulltext filter. This does not necessarily mean that the full text is available to you, dear reader; rather, it means that we have indexed the full text and can use it to help power searches. If you are trying to find the full text for yourself, try looking in open_access.oa_url.

We get access to the full text in one of two ways: either using an open-access PDF, or using N-grams obtained from the Internet Archive. You can learn where a work's full text came from at fulltext_origin.

About 57 million works have n-grams coverage through Internet Archive. OurResearch is the first organization to host this data in a highly usable way, and we are proud to integrate it into OpenAlex!

Curious about n-grams used in search? Browse them all via the API. Highly-cited works and less recent works are more likely to have n-grams, as shown by the coverage charts below:

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

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

/works attribute filters

/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

from_updated_date

fulltext.search

Value: a search string

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

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

It's easy to get an author from from the API with: /authors/<entity_id>. Here's an example:

External IDs

You can look up authors using external IDs such as an ORCID:

Available external IDs for authors are:

Select fields

You can group works with the group_by parameter:

Or you can group using one the attributes below.

/works group_by attributes

Searching without a middle initial returns names with and without middle initials. So a search for "John Smith" will also return "John W. Smith".

Search a specific field

When searching for authors, there is no difference when using the search parameter or the filter display_name.search, since display_name is the only field searched when finding authors.

Autocomplete authors

You can autocomplete authors to create a very fast type-ahead style search function:

This returns a list of authors with their last known affiliated institution as the hint:

Search a specific field

The following fields can be searched within works:

Why can't I search by name of related entity (author name, institution name, etc.)?

Rather than searching for the names of entities related to works—such as authors, institutions, and sources—you need to search by a more unique identifier for that entity, like the OpenAlex ID. This means that there is a 2 step process:

Why can't you do this in just one step? Well, if you use the search term, "NYU," you might end up missing the ones that use the full name "New York University," rather than the initials. Sure, you could try to think of all possible variants and search for all of them, but you might miss some, and you risk putting in search terms that let in works that you're not interested in. Figuring out which works are actually associated with the "NYU" you're interested shouldn't be your responsibility—that's our job! We've done that work for you, so all the relevant works should be associated with one unique ID.

Autocomplete works

You can autocomplete works to create a very fast type-ahead style search function:

This returns a list of works titles with the author of each work set as the hint:

affiliations

List: List of objects, representing the affiliations this author has claimed in their publications. Each object in the list has two properties:

• years: a list of the years in which this author claimed an affiliation with this institution

cited_by_count

counts_by_year

Any works or citations older than ten years old aren't included. Years with zero works and zero citations have been removed so you will need to add those in if you need them.

created_date

display_name

String: The name of the author as a single string.

display_name_alternatives

List: Other ways that we've found this author's name displayed.

id

String: The OpenAlex ID for this author.

ids

Object: All the external identifiers that we know about for this author. IDs are expressed as URIs whenever possible. Possible ID types:

• twitter (String: this author's Twitter handle)

• wikipedia (String: this author's Wikipedia page)

last_known_institution (deprecated)

last_known_institutions

orcid

summary_stats

Object: Citation metrics for this author

While the 2-year mean citedness is normally a journal-level metric, it can be calculated for any set of papers, so we include it for authors.

updated_date

works_api_url

String: A URL that will get you a list of all this author's works.

We express this as an API URL (instead of just listing the works themselves) because sometimes an author's publication list is too long to reasonably fit into a single author object.

works_count

x_concepts

• score (Float): The strength of association between this author and the listed concept, from 0-100.

The DehydratedAuthor object

Works with more than 100 authors are truncated

To see the full list of authors, go to the individual record for the work, which is never truncated.

This affects filtering as well. So if you filter works using an author ID or ROR, you will not receive works where that author is listed further than 100 places down on the list of authors. We plan to change this in the future, so that filtering works as expected.

You can filter authors with the filter parameter:

/authors attribute filters

/authors convenience filters

default.search

Value: a search string

display_name.search

Value: a search string

has_orcid

Value: a Boolean (true or false)

last_known_institution.continent

Returns: authors where where the last known institution is in the chosen continent.

last_known_institution.is_global_south

Value: a Boolean (true or false)

You can group authors with the group_by parameter:

Or you can group using one the attributes below.

/authors group_by attributes

You can get lists of authors:

Which returns a response like this:

Page and sort authors

Sample authors

Select fields

You can filter sources with the filter parameter:

/sources attribute filters

/sources convenience filters

continent

Returns: sources that are associated with the chosen continent.

default.search

Value: a search string

display_name.search

Value: a search string

has_issn

Value: a Boolean (true or false)

is_global_south

Value: a Boolean (true or false)

It's easy to get a source from from the API with: /sources/<entity_id>. Here's an example: