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 availability checks we have made, all the requests for access our users have created, and all their declarations of support too.

The API uses JSON for all posts and responses. Links to example responses are shown for each api operation documented below.. When POSTing data, remember to set the Content-Type header to application/json, e.g. for curl this header is added like so: curl -H "Content-Type:application/json".

There are no enforced rate limits, so limit your requests to a maximum of one request per second. If we notice problems we'll suspend your account and contact you about your needs. Although most api operations do not require authorisation, we ask that you please obtain your own API key.

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

Include the API key you are provided in either a URL param called "apikey" or in a header called "x-apikey". So, a curl call to the availability operation below might look like so (if you choose to use headers): curl -H "Content-Type: application/json" -H "x-apikey: yourRegisteredApikey" 'https://api.openaccessbutton.org'

https://api.openaccessbutton.org


GET Example

This is the prefix for all api calls and simply returns an indication of api status. The API returns a json status success message and 200 response code if the api is operational; otherwise the API is not in operation.

/availability


GET Example

Provide a url-encoded URL in a parameter named "url". The api will accept DOIs, PMIDs, PMC IDs, titles, and citations all of which can alternately be passed in the "url" parameter. The API will try to guess which type is being provided. Alternately, the specific type can be passed in by using a more specific parameter name: "doi", "pmc", "pmid", "title", "citation". In any case, note that only one parameter can be provided, and the preference for which to provide is: url, doi, pmc, pmid, title, citation.

The response returned lists objects of any "availability" found, with each object declaring "type" (currently either article or data) and the "url" where this object is found.

The response also includes a list of any open "requests", each object showing the request "type" and the request "id".

Finally the response includes 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!

/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.

/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/: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