references/unpaywall.md
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 (retired)
GET /v2/search?query={text}&[email protected]
Retired on 2026-09-18; returns HTTP 410 Gone. Use OpenAlex /works?search=... for discovery, or find papers in PubMed/Semantic Scholar and use the supported Unpaywall DOI lookup. Do not retry the retired search route.
Response Format
DOI Lookup response
{
"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 |
Typical Workflow
- You have a DOI from PubMed, Crossref, or another source
- Call Unpaywall with the DOI
- Check
is_oaandbest_oa_location; useurl_for_pdfif non-null, otherwise the landing-page URL. OA does not guarantee a direct PDF. - Check
oa_statusto understand what kind of OA it is - If closed, report that Unpaywall found no OA copy. This does not establish that every possible copy requires a subscription.
Official sources reviewed 2026-09-30
- https://unpaywall.org/products/api
- https://unpaywall.org/data-format