API docs

Our API allows you to find out if an article, published at some URL but perhaps 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 some example responses - install a JSON viewer plugin to your browser to make them easier to read. Also, when POSTing data, remember to set the Content-Type header, e.g. for curl it is curl -H "Content-Type:application/json".

There are currently 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 yet require authorisation, always include your API key either in a URL param called "apikey" or a header called "x-apikey". Excessive anonymous usage may result in IP blocking.

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
Also at /find


(For info on how we check availability, read about our sources.)

GET Example

Provide a url-encoded URL in a parameter named "url".

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 (so there's not much we could usefully do with it).

/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


We are considering allowing creation of requests via the API. Would you find this useful? Let us know!

/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