API

Our API allows you to find out if an article, published at some URL but not freely available there, is freely available anywhere else. It can also check for supporting data too. You can also search all the availabilty checks we have made, all the requests for access our users have created, and all their declarations of support too.

This is a JSON API, and the docs link out to example responses. When POSTing data, remember to set the Content-Type header, e.g. for curl it is curl -H "Content-Type:application/json".

There are no enforced rate limits, so be nice (1 request per second). If we notice problems we'll suspend your account and contact you about your needs.

Although most endpoints do not require authorisation, please include your API key either in a URL param called "apikey" or a header called "x-apikey".

Please sign up / sign in to see your API key here.

https://api.openaccessbutton.org


GET Example

This is the root, it returns a status success message and 200 response code - if it does not, the API is down.

/availability


GET Example

Provide a url-encoded URL in a parameter named "url". It can also accept DOIs, PMIDs, PMC IDs, titles, and citations. Each of these can be passed in as the "url" parameter and the API will try to guess which is provided, or it can be specified by passing the specific type as the parameter name = "doi", "pmid", "pmc", "title", or "citation". Note that only one parameter should be provided, and the preference for which to provide is url, doi, pmc, pmid, title, citation.

The result lists objects of any "availability" we found, with each object declaring "type" (currently article or data) and the "url" where we found it.

Then there's a list of any open "requests", each object showing the request "type" and the request "id".

Finally there is an "accepts" list which shows what sorts of new requests we will accept - we currently only accept "article" or "data" requests, and we won't accept new requests if already available or already requested.

Note we do blacklist some URLs - see below for more info and how to check it.

POST

We are considering enabling bulk availability checks via the API. Would you find this useful? Let us know!

/availabilities


GET or POST Example

This provides an elasticsearch endpoint onto all the availability checks we have performed for URLs previously received to the system. This allows you to search and explore very effectively.

To make full use of this endpoint you should read the elasticsearch query DSL documentation (we are currently on ES 1.4, moving soon to 5.x).

The simple method is to add a url parameter called "q", with values to match. The wildcard is *, and logic AND, OR, etc can be used too. For example you can find all availability checks made on the sciencedirect website by users of our v1.0.0 plugin with the query ?q=*sciencedirect* AND plugin:oabutton_1.0.0

/blacklist


GET Example

Returns a list of our currently blacklisted URLs - we won't accept availability checks or requests for URLs on this list, because we believe the content will not contain anything we would consider to be a research article.

/scrape


GET Example

Provide a url-encoded URL in a parameter named "url", and this will return the metadata we can find.

See the example for returned metadata structure - note that we wil not necessarily support the same metadata for all scraped URLs, and we may change it over time, so don't assume a stable structure here.

/request


POST

Create a new request by POSTing a JSON object to this endpoint - remember content-type:"application/json". The JSON object must contain at least "url", which should provide the URL to create a request for. The "url" parameter can also be a DOI, PMID, PMC ID, title, or citation - NOTE these fields should NOT be provided speciifcally by name; just put the values in the "url" field.

We try to disambiguate requests to ensure there are as few duplicates as possible, so for DOI, PMID and PMC ID, these are best provided in a URL-like format - DOI can be provided as https://doi.org/10.1234/567890, PMID as https://www.ncbi.nlm.nih.gov/pubmed/12345678, and PMC ID as https://www.ncbi.nlm.nih.gov/pubmed/1234567.

The request "type" should also be provided, and can be "article" or "data". If not provided it defaults to "article".

Ideally, a "story" should also be provided, explaining why the request is necessary. Also an "email" should be provided which should be the email address of the author to contact about the request (we will try to find an email address if one is not provided).

A "title" and "doi" field can also be provided as extra information for the resource.

NOTE that it is possible to create a request even for something that is available, so before creating a request please use the /availability endpoint to check if the item is already available, and if we already have an open request for it.

The response will be a JSON object of the new request, which will include the new request ID in the "_id" parameter.

/request/:id


GET Example

Returns the request with the given :id. View the example to see the request object structure. Note that the metadata fields are all optional, so do not rely on them always being present.

/requests


GET or POST Example

This provides an elasticsearch endpoint onto all the requests we have created so far (works the same as /availabilities, see above).

/supports


GET or POST Example

This provides an elasticsearch endpoint onto all the declarations of support we have received for open requests. (works the same as /availabilities, see above).

For example to find every declaration of support for the request with ID RBNfJLPX382TZZtRR:
?q=rid:6GY6Afbg6xnYQGjbt

Or to find every declaration of support made by a user with username "jimmy":
?q=username:jimmy