NAV

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:

http://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:

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

We recommend using the bearer token approach.

Objects

Get All Objects


curl -X "GET" "http://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": "http://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" "http://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

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

The above command returns JSON structured like this:

{
  "total": 13,
  "per_page": 50,
  "current_page": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 1,
  "to": 13,
  "data": [
    {
      "id": 2052,
      "accession-loan-no": "A1726",
      "simple-name": "figurine",
      "full-name": "figurine of a frog",
      "collector-excavator": "Jones, Winslow, Mr",
      "collection-country": "Egypt",
      "description": "Frogs were a symbol of rebirth and regeneration in ancient Egypt and small amulets like this were often placed with burials.",
      ...
      "created_at": "2016-04-01 10:07:15",
      "updated_at": "2016-04-01 10:07:15",
      "original-object-url": null,
      "relevance": 1
    }
  ]
}

This endpoint full-text searches all objects for your keyword.

HTTP Request

GET object/<Keyword>

URL Parameters

Parameter Description
Keyword The keyword you wish to search for

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

Categories

Get All Categories


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

The above command returns JSON structured like this:

[
  {
    "name": "Antiquities",
    "slug": "antiquities"
  },
  ...
  {
    "name": "Numismatics",
    "slug": "numismatics"
  }
]

This endpoint retrieves all categories

HTTP Request

GET categories

Sites

Get All Sites


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

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "name": "RAMM"
  }
]

This endpoint retrieves all sites

HTTP Request

GET sites

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.