Introduction

Welcome to the SWCE API.

The API is a (mostly) RESTful service, with authentication handled by API tokens sent as a header or parameter on every request.

You can send us pull request for any changes you think should be made to these docs over on Github

API Endpoint

The API endpoint is:

https://api.swcollectionsexplorer.org.uk/api/v1/

Formats

By default, the API returns everything in JSON. We recommend you consume this, and provide an Accept: application/json header with each call, although you will receive json without it.

XML is also available on every request if you prefer it, just send us an Accept: application/xml header.

Rate Limiting

You can make 60 requests to the API every 60 seconds.

After this, you’ll receive an 429 Too Many Requests status.

You can check your rate limit status by reading the X-RateLimit-Limit and X-RateLimit-Remaining headers returned on every request.

Authentication

SWCE currently only offers API tokens to allow access to the API. You can register a new API token key at our developer portal.

SWCE requires the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer w0WlRHfwbbr4JUJygL

Alternatively, you can make any request and append an api_token parameter:

https://api.swcollectionsexplorer.org.uk/api/v1/sites?api_token=w0WlRHfwbbr4JUJygL

We recommend using the bearer token approach.

Objects

Get All Objects

curl -X "GET" "https://api.swcollectionsexplorer.org.uk/api/v1/objects" \
    -H "Authorization: Bearer w0WlRHfwbbr4JUJygL"

The above command returns JSON structured like this:

{
  "total": 11379,
  "per_page": 50,
  "current_page": 1,
  "last_page": 228,
  "next_page_url": "https://api.swcollectionsexplorer.org.uk/api/v1/objects?page=2",
  "prev_page_url": null,
  "from": 1,
  "to": 50,
  "data": [
    {
      "id": 1,
      "accession-loan-no": "71/1929",
      "simple-name": "door",
      "full-name": null,
      "collector-excavator": null,
      "collection-country": "England",
      ...
      "site": {
        "name": "RAMM"
      },
      "category": {
        "name": "Antiquities",
        "slug": "antiquities"
      }
    },
    ...
  ]
}

This endpoint retrieves all objects.

HTTP Request

GET objects

Query Parameters

Parameter	Default	Description
site	null	Limit results to only one site ID
since	null	Only return objects modified since this timestamp (2016-04-10 18:00:00 format)
category	null	Limit results to this category slug
per_page	50	The number of results per page (min 10, max 250)

Get a Specific Object

curl -X "GET" "https://api.swcollectionsexplorer.org.uk/api/v1/object/1" \
    -H "Authorization: Bearer w0WlRHfwbbr4JUJygL"

The above command returns JSON structured like this:

{
  "id": 1,
  "accession-loan-no": "160/1999",
  "simple-name": "architectural fragment",
  "full-name": "label stop",
  "collector-excavator": "Pearce, Nan, Mrs",
  "collection-country": "England",
  "description": "This architectural fragment is shaped as a queen’s head with curly hair. It was salvaged from a demolished house in Membury, Devon, where it had been used in a 20th century fireplace. It was probably once part of the local church.",
  "mint": null,
  "medium": null,
  "geology-period": null,
  "common-name": "label stop",
  "family": null,
  ...
  "site": {
    "name": "RAMM"
  },
  "category": {
    "name": "Antiquities",
    "slug": "antiquities"
  }
}

This endpoint retrieves a specific object.

HTTP Request

GET object/<ID>

URL Parameters

Parameter	Description
ID	The ID of the object to retrieve

Errors

The SWCE API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request is invalid
401	Unauthorized – Your API key is not valid
403	Forbidden – The endpoint requested is hidden for administrators only
404	Not Found – The specified item could not be found
405	Method Not Allowed – You tried to access a item with an invalid method
406	Not Acceptable – You requested a format that isn’t json or xml
429	Too Many Requests – You have been rate limited.
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.