Collections Online API

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" -A "Your User Agent / 1.0" https://collection.sciencemuseumgroup.org.uk/search?filter%5Bcategories%5D=Computing%20%26%20Data%20Processing

Individual record

curl -ig -H "Accept: application/json" -A "Your User Agent / 1.0" https://collection.sciencemuseumgroup.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": "https://collection.sciencemuseumgroup.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": "https://collection.sciencemuseumgroup.org.uk/search?q=Charles&page[number]=0&page[size]=1",
    "last": "https://collection.sciencemuseumgroup.org.uk/search?q=Charles&page[number]=8&page[size]=1",
    "prev": "https://collection.sciencemuseumgroup.org.uk/search?q=Charles&page[number]=2&page[size]=1",
    "next": "https://collection.sciencemuseumgroup.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": "https://collection.sciencemuseumgroup.org.uk/objects/co34119/thorn-ericsson-astrofon-telephone-1981-telephone"
    }
  }
}