Unpaywall API

Unpaywall tells you whether a legal, free copy of a scholarly article exists. Given a DOI, it returns open access status, PDF links, and location details.

Base URL

https://api.unpaywall.org/v2

Authentication

No API key. You must include your email address as a query parameter: [email protected]

Important: Use a real email address. Unpaywall rejects placeholder emails like [email protected] with HTTP 422.

Rate Limits

100,000 calls per day. For heavier use, download the database snapshot.

Key Endpoints

1. DOI Lookup

GET /v2/{doi}[email protected]

Example:

https://api.unpaywall.org/v2/10.1038/[email protected]

2. Search (unreliable)

GET /v2/search?query={text}&[email protected]

Warning: The search endpoint has been returning HTTP 500 errors as of March 2026. It may be deprecated or intermittently broken. Use DOI lookups instead -- find papers via PubMed/OpenAlex/Semantic Scholar first, then check OA status per-DOI.

Parameter	Description
`query`	Search text. Supports quoted phrases, `OR`, `-` negation
`is_oa`	`true` or `false` -- filter by OA status
`page`	Page number (1-indexed), 50 results per page

Response Format

DOI Lookup response

json

{
  "doi": "10.1038/nature12373",
  "doi_url": "https://doi.org/10.1038/nature12373",
  "title": "Nanometre-scale thermometry in a living cell",
  "year": 2013,
  "published_date": "2013-07-31",
  "genre": "journal-article",
  "publisher": "Springer Nature",
  "is_oa": true,
  "oa_status": "green",
  "best_oa_location": {
    "url": "https://dash.harvard.edu/bitstream/1/...",
    "url_for_pdf": "https://dash.harvard.edu/bitstream/1/...pdf",
    "url_for_landing_page": "https://dash.harvard.edu/handle/...",
    "host_type": "repository",
    "version": "acceptedVersion",
    "license": "cc-by",
    "is_best": true,
    "oa_date": "2016-01-01"
  },
  "first_oa_location": {...},
  "oa_locations": [...],
  "has_repository_copy": true,
  "journal_name": "Nature",
  "journal_issns": "0028-0836,1476-4687",
  "journal_issn_l": "0028-0836",
  "journal_is_oa": false,
  "journal_is_in_doaj": false,
  "z_authors": [
    {"raw_author_name": "G. Kucsko", "author_position": "first"},
    {"raw_author_name": "P. C. Maurer", "author_position": "middle"}
  ]
}

OA Status values

Status	Meaning
`gold`	Published in a fully OA journal
`hybrid`	OA in a subscription journal (publisher-hosted)
`bronze`	Free to read on publisher site but no OA license
`green`	Available via a repository (e.g., institutional, preprint)
`closed`	No free legal copy found

OA Location fields

Field	Description
`url`	Best URL (PDF if available, else landing page)
`url_for_pdf`	Direct PDF URL (null if no PDF)
`url_for_landing_page`	Landing page URL
`host_type`	`publisher` or `repository`
`version`	`submittedVersion`, `acceptedVersion`, `publishedVersion`
`license`	e.g., `cc-by`, `cc-by-nc`, `implied-oa`, or null
`is_best`	Whether this is the `best_oa_location`
`oa_date`	When first available at this location

Search response

json

{
  "results": [
    {
      "response": {...},
      "score": 42.5,
      "snippet": "...text with <b>highlighted</b> matches..."
    }
  ]
}

Typical Workflow

You have a DOI from PubMed, Crossref, or another source
Call Unpaywall with the DOI
Check is_oa -- if true, use best_oa_location.url_for_pdf for the free PDF
Check oa_status to understand what kind of OA it is
If closed, oa_locations will be empty -- the article requires a subscription