The Adam Matthew API

The Adam Matthew API can be used to return metadata and full-text from documents, images and sections for Adam Matthew Collections. The API is RESTful and currently returns data in a JSON format provided a requestor uses a valid URL and API Key to retireve information.

OCR data or 'full-text' is returned from the API when an individual image or document is requested by its 'id' parameter. The 'id' parameter can be obtained when running a query that returns items with ids.

Example Request

A request to the API is simply made via a URL containing information about the collection you would like to request from, what type of item you would like to return (documents, images or sections) and some URL parameters with extra information about the request along with an API Key which confirms you are from a particular organisation and are allowed to access the API.


Example Responses

The response is a response object represented in JSON including a time the request was made, what version of the API you are using (we are currently on version 1.0) and how many results have been returned. The 'data' attribute contains an array of all the items returned by the request. If there is an error, this data attribute will be replaced by an 'error' attribute.

Successful Response

  "timestamp": "11/12/2015 11:37:59",
  "version": "1.0",
  "totalResults": 1,
  "data": [
      "type": "document",
      "collection": "Mass Observation",
      "identifier": "WorktownCollection-Box 9",
      "uri": "http://www.massobservation.amdigital.co.uk/Documents/Details/WorktownCollection-Box 9",
      "metadata": {
        "title": "MUNICIPAL POLITICS",
        "documentType": "Worktown Collection",
        "reference": "Box 9",
        "source": "University of Sussex",
        "rights": "Mass Observation Archive. University of Sussex Special Collections",
        "fullText": "false"

Error Response

  "timestamp": "11/12/2015 11:45:05",
  "totalResults": 0,
  "error": {
    "code": 401,
    "message": "Unauthorised",
    "details": "No further information is available for this error"