Note

Created: 2020-07-23 11:52:13 Platform: Email Email
Title Unpaywall Schema
Note:



Data Format

Overview

The database snapshot, Simple Query Tool, REST API, and Data Feed products all return JSON-formatted data. For simplicity, that data is organized under the same schema in all cases; that schema is informally described on this page.
Regardless of the source, each record returned consists of one DOI Object, containing resource metadata. Each DOI Object in turn contains a list of zero or more OA Location Objects.

DOI object

The DOI object is more or less a row in our main database...it's everything we know about a given DOI-assigned resource, including metadata about the resource itself, and information about its OA status. It includes a list of zero or more OA Location Objects, as well as a best_oa_location property that's probably the OA Location you'll want to use.


best_oa_location
Object|null
The best OA Location Object we could find for this DOI.

The "best" location is determined using an algorithm that prioritizes publisher-hosted content first (eg Hybrid or Gold), then prioritizes versions closer to the version of record (PublishedVersion over AcceptedVersion), then more authoritative repositories (PubMed Central over CiteSeerX).
Returns null if we couldn't find any OA Locations.


data_standard
Integer
Indicates the data collection approaches used for this resource.

Possible values

  • 1 First-generation hybrid detection. Uses only data from the Crossref API to determine hybrid status. Does a good job for Elsevier articles and a few other publishers, but most publishers are not checked for hybrid.
  • 2 Second-generation hybrid detection. Uses additional sources, checks all publishers for hybrid. Gets about 10x as much hybrid. data_standard==2 is the version used in the paper we wrote about the dataset.



doi
String
The DOI of this resource.
This is always lowercase.

doi_url
String
The DOI in hyperlink form.
This field simply contains "https://doi.org/" prepended to the doi field. It expresses the DOI in its correct format according to the Crossref DOI display guidelines.

genre
String
The type of resource.
Currently the genre is identical to the Crossref-reported type of a given resource. The "journal-article" type is most common, but there are many others.

is_paratext
Boolean
Is the item an ancillary part of a journal, like a table of contents?

is_oa
Boolean
Is there an OA copy of this resource.
Convenience attribute; returns true when best_oa_location is not null.

journal_is_in_doaj
Boolean
Is this resource published in a DOAJ-indexed journal.
Useful for defining whether a resource is Gold OA (depending on your definition, see also journal_is_oa).

journal_is_oa
Boolean
Is this resource published in a completely OA journal.
Useful for defining whether a resource is Gold OA. Includes any fully-OA journal, regardless of inclusion in DOAJ. This includes journals by all-OA publishers and journals that would otherwise be all Hybrid or Bronze OA. See here for more information on OA journals.

journal_issns
String
Any ISSNs assigned to the journal publishing this resource.
Separate ISSNs are sometimes assigned to print and electronic versions of the same journal. If there are multiple ISSNs, they are separated by commas. Example: 1232-1203,1532-6203

journal_issn_l
String
A single ISSN for the journal publishing this resource.
An ISSN-L can be used as a primary key for a journal when more than one ISSN is assigned to it. Resources' journal_issns are mapped to ISSN-Ls using the issn.org table, with some manual corrections.

journal_name
String
The name of the journal publishing this resource.
The same journal may have multiple name strings (eg, "J. Foo", "Journal of Foo", "JOURNAL OF FOO", etc). These have not been fully normalized within our database, so use with care.

oa_locations
List
List of all the OA Location objects associated with this resource.
This list is unnecessary for the vast majority of use-cases, since you probably just want the best_oa_location. It's included primarily for research purposes.

oa_status
String
The OA status, or color, of this resource.
Classifies OA resources by location and license terms as one of: gold, hybrid, bronze, green or closed. See here for more information on how we assign an oa_status.

published_date
String|Null
The date this resource was published.
As reported by the publishers, who unfortunately have inconsistent definitions of what counts as officially "published." Returned as an ISO8601-formatted timestamp, generally with only year-month-day.

publisher
String
The name of this resource's publisher.
Keep in mind that publisher name strings change over time, particularly as publishers are acquired or split up.

title
String
The title of this resource.
It's the title. Pretty straightforward.

updated
String
Time when the data for this resource was last updated.
Returned as an ISO8601-formatted timestamp. Example: 2017-08-17T23:43:27.753663

year
Integer|Null
The year this resource was published.
Just the year part of the published_date

z_authors
List of Crossref Contributor objects
The authors of this resource.
These are formatted as a list of Crossref Contributor objects, which are described in the Crossref API docs here.

OA Location object

The OA Location object describes particular place where we found a given OA article. The same article is often available from multiple locations, and there may be differences in format, version, and license depending on the location; the OA Location object describes these key attributes. An OA Location Object is always a Child of a DOI Object.


evidence
String
How we found this OA location.

Used for debugging. Don’t depend on the exact contents of this for anything, because values are subject to change without warning. Example values:

  • oa journal (via journal title in doaj) We found the name of the journal that publishes this article in the DOAJ database.
  • oa repository (via pmcid lookup) We found this article in an index of PubMed Central articles.



host_type
String
The type of host that serves this OA location.

There are two possible values:

  • publisher means this location is served by the article’s publisher (in practice, this usually means it is hosted on the same domain the DOI resolves to).
  • repository means this location is served by an Open Access repository. Preprint servers are considered repositories even if the DOI resolves there.



is_best
Boolean
Is this location the best_oa_location for its resource.
See the DOI object's best_oa_location description for more on how we select which location is "best."

license
String|Null
The license under which this copy is published.

We return several types of licenses:

  • Creative Commons licenses are uniformly abbreviated and lowercased. Example: cc-by-nc
  • Publisher-specific licenses are normalized using this format: acs-specific: authorchoice/editors choice usage agreement
  • When we have evidence that an OA license of some kind was used, but it’s not reported directly on the webpage at this location, this field returns implied-oa



pmh_id
String|Null
OAI-PMH endpoint where we found this location.
This is primarily for internal debugging. It's Null for locations that weren't found using OAI-PMH.

updated
String
Time when the data for this location was last updated.
Returned as an ISO8601-formatted timestamp. Example: 2017-08-17T23:43:27.753663

url
String
The url_for_pdf if there is one; otherwise landing page URL.

When we can't find a url_for_pdf (or there isn't one), this field uses the url_for_landing_page, which is a useful fallback for some use cases.


url_for_landing_page
String
The URL for a landing page describing this OA copy.

When the host_type is "publisher" the landing page usually includes HTML fulltext.


url_for_pdf
String|Null
The URL with a PDF version of this OA copy.

Pretty much what it says.


version
String
The content version accessible at this location.

We use the DRIVER Guidelines v2.0 VERSION standard to define versions of a given article; see those docs for complete definitions of terms. Here's the basic idea, though, for the three version types we support:

  • submittedVersion is not yet peer-reviewed.
  • acceptedVersion is peer-reviewed, but lacks publisher-specific formatting.
  • publishedVersion is the version of record.




Tags:
DOIs in Note:
Attachments

Referred Content

Platform: Referred Content
Referred Content Text
Tags:
URLs in Note: