Our APIs
This documentation is for the API launched in late 2017, and does not apply to previous versions of our APIs.
User Accounts
You will need an API key. View your API key by clicking on the 'Admin' tab and logging in. If you do not have an account, feel free to Create One
Object Retrieval API
The object retrieval API provides a machine interface for downloading object metadata.
Using the API
The API endpoint is available at https://v2.sherpa.ac.uk/cgi/retrieve
Examples
- /cgi/retrieve?item-type=funder&api-key=YOUR-API-KEY&format=Json&limit=5&offset=10
- /cgi/retrieve?item-type=funder&api-key=YOUR-API-KEY&format=Json&filter=[["country","equals","ca"]]
Parameters
| Parameter Name | Required | Description | Type |
|---|---|---|---|
| item-type | Yes | The type of object to retrieve | set('funder', 'funder_group') |
| api-key | Yes | Your API Key, part of your Sherpa user account | API Key |
| format | Yes | The format of the output | set('Json','Ids') |
| order | No | The order of the records | csv fieldnames, e.g. name,-id -- supports the same fields as filters (see below) with the option of a '-' being added to denote reversed direction |
| limit | No | The maximum number of records to retrieve. Cannot be greater than 100, and if unspecified, defaults to 100 | integer between 0 and 100 |
| offset | No | Combines with order and limit to give paging. The first record of the returned results set will be the N+1th record (indexing starts at 0) | Positive Integer |
| filter | No | A json array specifying filter conditions that must be matched in all returned results | Json encoded filter arrays (see below) |
More on Filters
The filter parameter is a JSON array containing up to three JSON arrays. Each of these arrays contain exactly three parts: a fieldname, a match operator and a value. An example of a filter might be:
- [["id","equals","57"]]
- [["name","contains word","cancer"],["country","equals","ca"]]
Fields available to filters (and ordering) are defined on a type-by-type basis:
| fields for funder | |
|---|---|
| name | synonym of name_name |
| name_name | the name (the name subfield of the name field) |
| acronym | synonym of name_acronym |
| name_acronym | the acronym (the acronym subfield of the name field) |
| country | The two-letter country code |
| funderid | synonym of id |
| id | the internal id of the item |
The following Operators are supported:
| equals | match a whole value |
|---|---|
| contains word | match a string that contains a word as defined in the value (note: this is not substring matching) |
| gte | Used for numeric and date types. Greater than or equal to. |
| lte | Used for numeric and date types. Less than or equal to. |