Object Retrieval API
The object retrieval API provides a machine interface for downloading object metadata.
The API endpoint is available at https://v2.sherpa.ac.uk/cgi/retrieve
Examples
- /cgi/retrieve?item-type=publication&api-key=YOUR-API-KEY&format=Json&limit=5&offset=10
- /cgi/retrieve?item-type=publisher&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', 'repository', 'publisher', 'publisher_policy', 'publication') |
| 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"]]
- [["date_modified","gte","2020-09-10T14:15:48Z"]]
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. |
More on Dates
The following options for dates are supported:
| Example | Description |
|---|---|
| 2020 | Specific Year |
| 2020-07 | Specific Month |
| 2020-07-05 | Specific Day |
| 2020-07-05T14:15:48Z | ISO 8601 timestamp. Note that time zones are not supported, so 'Z' must be used. |
Fields available to filters (and ordering) are defined on a type-by-type basis:
Returned Data
Two formats are currently supported; Ids and Json. Ids will return plain text with an object ID on each line. As JSON, an object is containing the name-value pair of 'items' and an array of objects.
{
"items" : [
{ ... },
{ ... },
{ ... },
{ ... },
{ ... }
]
}
The objects contained within the items array will be the results of your API query, and will depend on the object type requested. Please see our Metadata Schema for a full description of the fields and value types of each object.