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://dev.api.cottagelabs.com/service/oab'

https://dev.api.cottagelabs.com/service/oab


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. Please remember to include the header: content-type:"application/json" The JSON object itself must contain at least the "url" parameter - the URL to create a request for. The "url" parameter can also be formatted as a url or alternately as a DOI, PMID, PMC ID, title, or citation. NOTE that in any case, these values should be put in the "url" parameter, NOT in other parameter names (like doi, citation, etc).

When you provide DOI, PMID and PMC ID values in the "url parameter, please format the value in a URL 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. (This helps us disambiguate requests to ensure there are as few duplicates as possible).

The request "type" parameter should also be provided with a value of "article" or "data". If not provided the type defaults to "article".

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

"title" and "doi" parameters can also be provided as additional information about the resource.

To avoid creating a request for a resource that is already available, please use the /availability endpoint to determine if the item is available or 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 endpoint allows you to flexibly search and explore availability of all URLs previously received. These are indexed by an elasticsearch so some knowledge of straightforward elasticsearch search semantics is necessary.

A simple search can be created by adding a url parameter called "q" (for query) and provide values you would like to match. For example to 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 Note that in a query, * can be used as a wildcard to match anything (in the example, before and after "sciendedirect"). Also note that AND, OR and other logic can be used to combine search values in a query.

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

/blacklist


GET Example

Returns a list of our currently blacklisted domains or 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

Returns metadata for a provided URL. Simple provide a url-encoded URL in a parameter named "url".

Try the example above to see the returned metadata structure. Note that we will not necessarily support the same metadata for all scraped URLs, and we may change it over time, so don't assume a stable structure.

/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 endpoint allows you to flexibly search and explore all requests we have received. As with the /availabilities endpoint above, valid elasticsearch queries are accepted (see /availabilities above for more information).

/supports


GET or POST Example

This endpoint allows you to flexibly search and explore all support declarations we have received for open requests. As with the /availabilities and /requests endpoints above, valid elasticsearch queries are accepted (see /availabilities above for more information).

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