Collections Online API

Jamie Unwin edited this page Feb 28, 2017 · 27 revisions

Visit the following repo for some JavaScript examples of retrieving our API data. https://github.com/TheScienceMuseum/collectionsonline-api

Quick examples

Result set

curl -ig -H "Accept: application/json" http://collection.sciencemuseum.org.uk/search?filter%5Bcategories%5D=Computing%20%26%20Data%20Processing

Individual record

curl -ig -H "Accept: application/json" http://collection.sciencemuseum.org.uk/objects/co34119/thorn-ericsson-astrofon-telephone-1981-telephone

The Collections Online API follows the JSONAPI specification.

GET /search

Search all collections.

Query parameters

Name Type Required Description
q string Yes Search term
random integer No Number of random records to return for the specified search criteria
page[number] integer No Zero indexed pagination page number to retrieve
page[size] integer No Pagination page size (default 50, max 100)
fields[TYPE] string No CSV fields to return for a resource TYPE
Facet filter parameters

(Plural parameters are optionally multiple)

To comply with the jsonapi spec these filters are also available as filter[PARAM_NAME].

All
Name Type Required Description
date[from] date No e.g. 1829, 1900-12 or 1984-04-19
date[to] date No e.g. 1829, 1900-12 or 1984-04-19
places string No Associated geographical places
Objects
Name Type Required Description
type string No e.g. Model locomotive
makers string No Name of maker(s)/creator(s)
people string No Associated people e.g. Robert Stephenson
organisations string No ALIAS for "people" e.g. Liverpool & Manchester Railway
categories string No e.g. Locomotives and Rolling Stock
museum enum No NRM, SMG, NMeM or MSI
on_display booelan No Whether object is currently on display
location string No Object's current museum location (only if on_display)
People
Name Type Required Description
birth[place] string No Name of place person was born
birth[date] date No ALIAS for "date[from]"
death[date] date No ALIAS for "date[to]"
occupation string No Occupation of the person
Documents
Name Type Required Description
type string No e.g. Engineering
makers string No Name of maker(s)/creator(s)
people string No Associated people e.g. Robert Stephenson
organisations string No ALIAS for "people" e.g. Liverpool & Manchester Railway
archive string No Name of archive
formats string No e.g. bound volume, large format document or photograph
image_licences string No Licence types for imagery e.g. CC BY-NC-SA

Example

GET /search?q=Charles&page[number]=3&page[size]=1 HTTP/1.1
// HTTP/1.1 200 OK
// Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "people", // or objects or documents
      "id": "cp22969",
      "attributes": {
        // Resource attributes TBC
      },
      "relationships": {
        // Resource relationships TBC
        // Format: http://jsonapi.org/format/#document-compound-documents
      },
      "meta": {
        "score": 0.076713204 // Relevance of result
      },
      "links": {
        "self": "http://collection.sciencemuseum.org.uk/people/cp22969" // Link to this resource
      }
    }
  ],
  "meta": {
    "total_pages": 8,
    "count": {
      "type": {
        "all": 8,
        "people": 5,
        "objects": 2,
        "documents": 1
      }
    },
     "filters": {
      "birth[place]": [
        {
          "value": "London",
          "count": 2
        },
        {
          "value": "Portsmouth",
          "count": 1
        }
      ]
    }
  },
  "links": {
    "first": "http://collection.sciencemuseum.org.uk/search?q=Charles&page[number]=0&page[size]=1",
    "last": "http://collection.sciencemuseum.org.uk/search?q=Charles&page[number]=8&page[size]=1",
    "prev": "http://collection.sciencemuseum.org.uk/search?q=Charles&page[number]=2&page[size]=1",
    "next": "http://collection.sciencemuseum.org.uk/search?q=Charles&page[number]=4&page[size]=1"
  }
}

TODO: Define response attributes and relationships for each resource type


GET /search/objects

GET /search/people

GET /search/documents

Search restricted to particular resource type. See GET /search for parameters.


GET /objects/{id}/{slug?}

GET /people/{id}/{slug?}

GET /documents/{id}/{slug?}

Get data for the given resource ID.

Path parameters

Name Type Required Description
id string Yes Resource ID
slug string No Optional (ignored) SEO friendly slug
GET /objects/co34119/thorn-ericsson-astrofon-telephone-1981-telephone HTTP/1.1
// HTTP/1.1 200 OK
// Content-Type: application/vnd.api+json

{
  "data": {
    "type": "objects",
    "id": "smga-objects-26803",
    "attributes": {
      // Resource attributes TBC
    },
    "relationships": {
      // Resource relationships TBC
      // Format: http://jsonapi.org/format/#document-compound-documents
    },
    "links": {
      "self": "http://collection.sciencemuseum.org.uk/objects/co34119/thorn-ericsson-astrofon-telephone-1981-telephone"
    }
  }
}