141 lines
4.0 KiB
Markdown
141 lines
4.0 KiB
Markdown
---
|
|
title: "Unpaywall API"
|
|
task: ""
|
|
lineage_type: import
|
|
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/paper-lookup/references/unpaywall.md
|
|
upstream_sha: 9c9bd2e9
|
|
imported_at: 2026-06-27
|
|
prompt_class: prompt
|
|
upstream_changes: accepted
|
|
author: upstream
|
|
validated: false
|
|
---
|
|
|
|
# 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
|
|
|
|
1. You have a DOI from PubMed, Crossref, or another source
|
|
2. Call Unpaywall with the DOI
|
|
3. Check `is_oa` -- if true, use `best_oa_location.url_for_pdf` for the free PDF
|
|
4. Check `oa_status` to understand what kind of OA it is
|
|
5. If closed, `oa_locations` will be empty -- the article requires a subscription
|