OpenAPI Specification
openapi: 3.0.3
info:
title: Unpaywall DOI Lookup API
description: The Unpaywall REST API gives anyone free, programmatic access to the Unpaywall database of open access scholarly articles. The database covers over 120 million articles with Crossref DOIs and links to free, legal full-text versions where available. Authentication is done via an email address query parameter (no API key required). Usage is limited to 100,000 calls per day.
version: 2.0.0
contact:
name: Unpaywall Support
url: https://support.unpaywall.org
license:
name: Creative Commons CC0
url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://api.unpaywall.org/v2
description: Unpaywall API v2
tags:
- name: DOI Lookup
description: Look up open access status by DOI
paths:
/{doi}:
get:
operationId: getByDoi
summary: Get Open Access Status by DOI
description: Retrieve open access information for a scholarly article identified by its DOI. Returns the OA status, best open access location, all available OA locations, journal metadata, and author information.
tags:
- DOI Lookup
parameters:
- name: doi
in: path
required: true
schema:
type: string
description: The DOI of the article (e.g., 10.1038/nature12373)
example: 10.1038/nature12373
- name: email
in: query
required: true
schema:
type: string
format: email
description: Your email address — required for all API calls to identify usage
example: you@example.com
responses:
'200':
description: Article OA status and location data
content:
application/json:
schema:
$ref: '#/components/schemas/UnpaywallObject'
'404':
description: DOI not found in Unpaywall database
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Invalid email or missing required parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
UnpaywallObject:
type: object
description: The full Unpaywall object for a scholarly article, containing OA status, all open access locations, journal metadata, and bibliographic information.
required:
- doi
- is_oa
- data_standard
properties:
doi:
type: string
description: The DOI of the article (lowercased)
example: 10.1038/nature12373
doi_url:
type: string
format: uri
description: The canonical URL for the DOI (https://doi.org/{doi})
example: https://doi.org/10.1038/nature12373
title:
type:
- string
- 'null'
description: Article title
example: Measurement of the Higgs boson mass from the H→γγ and H→ZZ*→4ℓ channels
genre:
type:
- string
- 'null'
description: Article type from Crossref (journal-article, book-chapter, conference-paper, etc.)
example: journal-article
is_paratext:
type: boolean
description: True if this is metadata about a journal issue, conference proceeding, or editorial (paratext rather than research). These should generally be filtered out.
default: false
published_date:
type:
- string
- 'null'
description: ISO 8601 publication date (YYYY-MM-DD or partial)
example: '2013-07-30'
year:
type:
- integer
- 'null'
description: Publication year
example: 2013
journal_name:
type:
- string
- 'null'
description: Journal display name
example: Nature
journal_issns:
type:
- string
- 'null'
description: Comma-separated list of ISSNs for the journal
example: 0028-0836,1476-4687
journal_issn_l:
type:
- string
- 'null'
description: The linking ISSN (ISSN-L) for the journal
example: 0028-0836
journal_is_oa:
type: boolean
description: True if the journal is fully open access (gold OA)
default: false
journal_is_in_doaj:
type: boolean
description: True if the journal appears in the Directory of Open Access Journals (DOAJ)
default: false
publisher:
type:
- string
- 'null'
description: Publisher name from Crossref
example: Springer Nature
is_oa:
type: boolean
description: True if there is a free, legal full-text version of this article available. This is the primary field for determining open access status.
oa_status:
type:
- string
- 'null'
description: 'The open access color/type: gold, hybrid, bronze, green, or closed. Gold = fully OA journal. Hybrid = OA in a subscription journal. Bronze = free to read but no explicit license. Green = repository copy.'
enum:
- gold
- hybrid
- bronze
- green
- closed
- null
example: gold
has_repository_copy:
type: boolean
description: True if there is a copy in a repository (green OA)
default: false
best_oa_location:
oneOf:
- $ref: '#/components/schemas/OALocation'
- type: 'null'
description: The best (highest quality) open access location for this article
first_oa_location:
oneOf:
- $ref: '#/components/schemas/OALocation'
- type: 'null'
description: The first open access location found (chronologically)
oa_locations:
type: array
items:
$ref: '#/components/schemas/OALocation'
description: All open access locations found for this article
oa_locations_embargoed:
type: array
items:
$ref: '#/components/schemas/OALocation'
description: Open access locations that are currently under embargo
data_standard:
type: integer
description: Version of data processing used. 2 = current standard with full OA location details. Used to filter results to most complete records.
example: 2
z_authors:
type:
- array
- 'null'
description: Author metadata from Crossref (deprecated field name, kept for backwards compatibility). Each item is a Crossref author object.
items:
type: object
properties:
given:
type: string
description: Author given name
family:
type: string
description: Author family name
ORCID:
type: string
description: Author ORCID identifier
affiliation:
type: array
items:
type: object
properties:
name:
type: string
updated:
type:
- string
- 'null'
description: ISO 8601 timestamp when this record was last updated in Unpaywall. May show "deprecated" in some records.
ErrorResponse:
type: object
description: Error response from the Unpaywall API
properties:
HTTP_status_code:
type: integer
description: HTTP status code
example: 404
error:
type: boolean
description: Always true for error responses
default: true
message:
type: string
description: Human-readable error message
example: Sorry, we don't have any data for that DOI
OALocation:
type: object
description: A single open access location for a scholarly article
properties:
url:
type:
- string
- 'null'
format: uri
description: URL for the best available version (PDF or landing page)
example: https://www.nature.com/articles/nature12373.pdf
url_for_pdf:
type:
- string
- 'null'
format: uri
description: Direct URL to the PDF if available
example: https://arxiv.org/pdf/1304.1068
url_for_landing_page:
type:
- string
- 'null'
format: uri
description: URL to the article landing page
example: https://doi.org/10.1038/nature12373
host_type:
type:
- string
- 'null'
description: Where the OA version is hosted (publisher or repository)
enum:
- publisher
- repository
- null
example: repository
version:
type:
- string
- 'null'
description: Version of the article (publishedVersion, acceptedVersion, submittedVersion). publishedVersion is the final typeset version. acceptedVersion is post-peer-review. submittedVersion is the pre-print.
enum:
- publishedVersion
- acceptedVersion
- submittedVersion
- null
example: acceptedVersion
license:
type:
- string
- 'null'
description: Open license identifier (cc-by, cc-by-sa, cc-by-nc, etc.)
example: cc-by
oa_date:
type:
- string
- 'null'
description: ISO 8601 date when this version became open access
example: '2013-07-30'
is_best:
type: boolean
description: True if this is the best OA location (same as best_oa_location)
endpoint_id:
type:
- string
- 'null'
description: Identifier of the OAI-PMH repository endpoint (if applicable)
pmh_id:
type:
- string
- 'null'
description: OAI-PMH record identifier from the repository
example: oai:arXiv.org:1304.1068
repository_institution:
type:
- string
- 'null'
description: Name of the institution operating the repository
example: Cornell University
evidence:
type:
- string
- 'null'
description: How Unpaywall found this OA location (may show "deprecated")
updated:
type:
- string
- 'null'
description: When this OA location record was last updated