Skills › Scientific Agent Skills › paper-lookup › unpaywall.md

unpaywall.md

113 lines · skills/paper-lookup/references/unpaywall.md at 5f2bc03

1# Unpaywall API

3Unpaywall 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.

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.

Raw lines 1 to 4

5## Base URL

7```

8https://api.unpaywall.org/v2

9```

Base URL

https://api.unpaywall.org/v2

Raw lines 5 to 10

11## Authentication

13No API key. You must include your **email address** as a query parameter: `?email=you@example.com`

15**Important:** Use a real email address. Unpaywall rejects placeholder emails like `test@example.com` with HTTP 422.

Authentication

No API key. You must include your email address as a query parameter: ?email=you@example.com

Important: Use a real email address. Unpaywall rejects placeholder emails like test@example.com with HTTP 422.

Raw lines 11 to 16

17## Rate Limits

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

Rate Limits

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

Raw lines 17 to 20

21## Key Endpoints

Key Endpoints

Raw lines 21 to 22

23### 1. DOI Lookup

25```

26GET /v2/{doi}?email=you@example.com

27```

29**Example:**

30```

31https://api.unpaywall.org/v2/10.1038/nature12373?email=you@example.com

32```

1. DOI Lookup

GET /v2/{doi}?email=you@example.com

Example:

https://api.unpaywall.org/v2/10.1038/nature12373?email=you@example.com

Raw lines 23 to 33

34### 2. Search (retired)

36```

37GET /v2/search?query={text}&email=you@example.com

38```

40**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.

2. Search (retired)

GET /v2/search?query={text}&email=you@example.com

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.

Raw lines 34 to 41

42## Response Format

Response Format

Raw lines 42 to 43

44### DOI Lookup response

45```json

46{

47 "doi": "10.1038/nature12373",

48 "doi_url": "https://doi.org/10.1038/nature12373",

49 "title": "Nanometre-scale thermometry in a living cell",

50 "year": 2013,

51 "published_date": "2013-07-31",

52 "genre": "journal-article",

53 "publisher": "Springer Nature",

54 "is_oa": true,

55 "oa_status": "green",

56 "best_oa_location": {

57 "url": "https://dash.harvard.edu/bitstream/1/...",

58 "url_for_pdf": "https://dash.harvard.edu/bitstream/1/...pdf",

59 "url_for_landing_page": "https://dash.harvard.edu/handle/...",

60 "host_type": "repository",

61 "version": "acceptedVersion",

62 "license": "cc-by",

63 "is_best": true,

64 "oa_date": "2016-01-01"

65 },

66 "first_oa_location": {...},

67 "oa_locations": [...],

68 "has_repository_copy": true,

69 "journal_name": "Nature",

70 "journal_issns": "0028-0836,1476-4687",

71 "journal_issn_l": "0028-0836",

72 "journal_is_oa": false,

73 "journal_is_in_doaj": false,

74 "z_authors": [

75 {"raw_author_name": "G. Kucsko", "author_position": "first"},

76 {"raw_author_name": "P. C. Maurer", "author_position": "middle"}

77 ]

78}

79```

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"}
  ]
}

Raw lines 44 to 80

81### OA Status values

82| Status | Meaning |

83|--------|---------|

84| `gold` | Published in a fully OA journal |

85| `hybrid` | OA in a subscription journal (publisher-hosted) |

86| `bronze` | Free to read on publisher site but no OA license |

87| `green` | Available via a repository (e.g., institutional, preprint) |

88| `closed` | No free legal copy found |

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

Raw lines 81 to 89

90### OA Location fields

91| Field | Description |

92|-------|-------------|

93| `url` | Best URL (PDF if available, else landing page) |

94| `url_for_pdf` | Direct PDF URL (null if no PDF) |

95| `url_for_landing_page` | Landing page URL |

96| `host_type` | `publisher` or `repository` |

97| `version` | `submittedVersion`, `acceptedVersion`, `publishedVersion` |

98| `license` | e.g., `cc-by`, `cc-by-nc`, `implied-oa`, or null |

99| `is_best` | Whether this is the `best_oa_location` |

100| `oa_date` | When first available at this location |

101

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

Raw lines 90 to 101

102## Typical Workflow

103

1041. You have a DOI from PubMed, Crossref, or another source

1052. Call Unpaywall with the DOI

1063. Check `is_oa` and `best_oa_location`; use `url_for_pdf` if non-null, otherwise the landing-page URL. OA does not guarantee a direct PDF.

1074. Check `oa_status` to understand what kind of OA it is

1085. If closed, report that Unpaywall found no OA copy. This does not establish that every possible copy requires a subscription.

109

Typical Workflow

You have a DOI from PubMed, Crossref, or another source
Call Unpaywall with the DOI
Check is_oa and best_oa_location; use url_for_pdf if non-null, otherwise the landing-page URL. OA does not guarantee a direct PDF.
Check oa_status to 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.

Raw lines 102 to 109

110## Official sources reviewed 2026-09-30

111

112- https://unpaywall.org/products/api

113- https://unpaywall.org/data-format

Official sources reviewed 2026-09-30

https://unpaywall.org/products/api
https://unpaywall.org/data-format

Raw lines 110 to 113