How Unpaywall finds a free paper
Yes, we can study and adapt its design. The browser extension and backend repositories publish their code under the MIT licence. Reading that published source is enough to understand the main process.
Standalone, offline explanation. Attach the saved .html file to share it. Source links require internet.The useful idea: find another available copy
Read its DOI: a stable scholarly identifier, often in the page’s metadata.
Look for an open version hosted by a publisher or repository.
Show a reading link, with its version and available licence information.
For example, a journal’s formatted edition may require a subscription while the author’s accepted manuscript is openly available through a university repository. Those editions can differ. The tool directs you to an available version; it does not obtain a subscriber’s decryption key.
Trace the decision yourself
This is an offline demonstration with invented records. It makes no network calls and does not claim to check a real paper.
What I found in the published extension
The code’s findDoi routine tries metadata names such as citation_doi, data attributes and publisher-specific patterns. runOadoi queries a DOI endpoint and reads best_oa_location.url. A separate path looks for a PDF link already on the page and tests whether it is accessible. getBestOaUrl prefers that checked local PDF, then the indexed location; the interface displays a coloured tab.
The inspected manifest declares Manifest V2 and broad page matching. This is a source snapshot, not verification of the currently distributed store build. Our own companion uses Manifest V3 and runs only when clicked. A PWA alone cannot inspect arbitrary browser tabs; a user must share or paste the identifier, or use a companion extension.
Where the work happens on the server
The public backend includes data processing, repository discovery and records describing available locations. Older ranking code scores host type, manuscript version, PDF availability and matching evidence, then filters and deduplicates locations. It distinguishes a published version, accepted manuscript and submitted manuscript.
Current-code caveat: in the source fetched today, the /v2/<doi> route normalises a DOI and retrieves a precomputed record through WunpaywallPub. That model returns stored JSON. The older ranking classes therefore show useful design history, but do not prove how every current production record is generated. The website’s deployed code may also differ from the repository.
Maintaining a large, accurate index and refreshing dead links is the substantial ongoing work. A small reader client can use that existing service rather than reproduce its whole database.
Publication processing · Location and ranking code · API routes · Current stored-record model
What we can reuse in Reading Room
- Identify a scholarly paper from a DOI supplied by you or detected by the companion.
- Make an explicit, user-initiated lookup. The API expects a contact email; disclose that the DOI and email go to Unpaywall before sending them. Do not reuse the original extension’s hard-coded contact address.
- Display the best and alternative locations, manuscript version and licence. Treat missing licence information as unknown.
- Keep no indexed location, unknown DOI and network failure as different outcomes.
- Open the source normally; only save text you are entitled to retain. A free reading link is not automatically permission to redistribute the paper.
This study did not call the API with your email, install Unpaywall, run its backend or add a live scholarly lookup to Reading Room. Its existing article library and access routes remain usable.
Will that get the Times article?
No DOI was identified for the Times story. Unpaywall is aimed at scholarly papers and preprints, so there is no established Unpaywall route to that news article.
We can reuse the broader idea—identify a work and look for an authorised accessible edition—for news. That requires matching headline, author, publication date and publisher, then checking candidate copies. A similar headline or a partial archive page is not enough. Reading Room already gathers library, publisher-sharing, author-copy and archive routes without pretending they guarantee full text.
Reuse and evidence
The inspected extension and backend licences permit reuse with their copyright and permission notices retained. Their licences cover their code; they do not grant rights to every paper. No upstream code is embedded in this original explanation or its demonstration.
Eight source files were read as text, never executed. A source inventory with retrieval time and SHA-256 fingerprints is included in the Reading Room package. This is an architecture inspection, not a full backend deployment audit.