This is the main function to retrieve comprehensive open access status information from Unpaywall data service. Please play nice with the API. For each user, 100k calls per day are suggested. If you need to access more data, there is also a data dump available. For more info see

  dois = NULL,
  email = Sys.getenv("roadoi_email"),
  .progress = "none",
  .flatten = FALSE



character vector, search by a single DOI or many DOIs. A rate limit of 100k requests per day is suggested. If you need to access more data, request the data dump instead.


character vector, mandatory! Unpaywall requires your email address, so that they can track usage and notify you when something breaks. Set email address in your `.Renviron` file with the option `roadoi_email` options(roadoi_email = "[email protected]"). You can open your `.Renviron` file calling `file.edit("~/.Renviron")`. Save the file and restart your R session. To stop sharing your email when using rcrossref, delete it from your `.Renviron` file.


Shows the plyr-style progress bar. Options are "none", "text", "tk", "win", and "time". See create_progress_bar for details of each. By default, no progress bar is displayed.


Simplify open access evidence output. If `TRUE` it transforms the nested column oa_locations so that each open access evidence variable has its own column and each row represents a single full-text. Following these basic principles of "Tidy Data" makes data analysis and export as a spreadsheet more straightforward.


The result is a tibble with each row representing a publication. Here are the returned columns and descriptions according to the API docu:

doiDOI (always in lowercase).
best_oa_locationlist-column describing the best OA location. Algorithm prioritizes publisher hosted content (eg Hybrid or Gold), then prioritizes versions closer to the version of record (PublishedVersion over AcceptedVersion), then more authoritative repositories (PubMed Central over CiteSeerX).
oa_locationslist-column of all the OA locations.
oa_locations_embargoedlist-column of locations expected to be available in the future based on information like license metadata and journals' delayed OA policies
data_standardIndicates the data collection approaches used for this resource. 1 mostly uses Crossref for hybrid detection. 2 uses a more comprehensive hybrid detection methods.
is_oaIs there an OA copy (logical)?
is_paratextIs the item an ancillary part of a journal, like a table of contents? See here for more information
genrePublication type
oa_statusClassifies OA resources by location and license terms as one of: gold, hybrid, bronze, green or closed. See here for more information
has_repository_copyIs a full-text available in a repository?
journal_is_oaIs the article published in a fully OA journal?
journal_is_in_doajIs the journal listed in the Directory of Open Access Journals (DOAJ).
journal_issnsISSNs, i.e. unique numbers to identify journals.
journal_issn_lLinking ISSN.
journal_nameJournal title, not normalized.
publisherPublisher, not normalized.
published_dateDate published
yearYear published.
titlePublication title.
updated_resourceTime when the data for this resource was last updated.
authorsLists author information (family name, given name and author role sequence), if available.

The columns best_oa_location. oa_locations and oa_locations_embargoed are list-columns that contain useful metadata about the OA sources found by Unpaywall.

If .flatten = TRUE the list-column oa_locations will be restructured in a long format where each OA fulltext is represented by one row.

These are:

endpoint_idUnique repository identifier.
evidenceHow the OA location was found and is characterized by Unpaywall?
host_typeOA full-text provided by publisher or repository.
is_bestIs this location the best_oa_location for its resource?
licenseThe license under which this copy is published, e.g. Creative Commons license.
pmh_idOAI-PMH endpoint where we found this location.
repository institutionHosting institution of the repository.
updatedTime when the data for this location was last updated.
urlThe url_for_pdf if there is one; otherwise landing page URL.
url_for_landing_pageThe URL for a landing page describing this OA copy.
url_for_pdfThe URL with a PDF version of this OA copy.
versionThe content version accessible at this location following the DRIVER 2.0 Guidelines (

Note that Unpaywall schema is only informally described. Check also


if (FALSE) { oadoi_fetch("10.1038/nature12373", email = "[email protected]") oadoi_fetch(dois = c("10.1016/j.jbiotec.2010.07.030", "10.1186/1471-2164-11-245"), email = "[email protected]") # flatten OA evidence roadoi::oadoi_fetch(dois = c("10.1186/s12864-016-2566-9", "10.1103/physreve.88.012814", "10.1093/reseval/rvaa038"), email = "[email protected]", .flatten = TRUE) }