Mass Observation Project COVID-19 Database API

Welcome to the Mass-Observing COVID-19 Database API (Application Programming Interface), supporting tool users and software developers to query the Mass-Observing COVID-19 Database programmatically.
The API provides access to all of the Database search functionality with machine readable results output.

Request an API key

In order to use the Mass Observation Project COVID-19 Database API, you will first have to request and API key.

» Click here to request an API key

Quick Start - Test harness

The API is published with a standards-compliant OpenAPI v3 definition, which can be consumed by any compliant client tool, or read manually.

The definition can be used with the Swagger client tool for easy testing - just try the API using this test page:

» Click here to use the Swagger User interface to the COVID-19 Database API.

API Key and Referer header

The API key must be provided with every API request, either as an HTTP GET variable X-API-Key=XXXX, or in the custom request header X-API-Key: XXXX.

Use content negotiation to switch between output types (XML, JSON):

API requests can select to receive responses in JSON or XML formats.

Accept header (or GET variable): either application/xml or application/json

Usage

The API provides two request types: filter for retrieving ids of valid search parameter values, and search for requesting COVID-19 Database results.

All search request parameters (except for full text and keywords) are specified using the id values from a filter request.

For example, to search the database for results of a specific gender, you will first perform a filter request to receive the list of the different gender id and value pairs to use in your search requests.

This is illustrated in the examples below.

Curl filter example

Fetch the list of genders in order to provide the id of the gender of interst in a Database search:

curl -X 'GET' \
'https://database.massobs.org.uk/api/filter/?filter=gender' \
-H 'Accept: application/json' \
-H 'X-API-KEY: xxx'

Curl search example

Carry out a COVID-19 Database search using the gender id 1 ("Male"):

curl -X 'GET' \
'https://database.massobs.org.uk/api/search/?gender=1' \
-H 'Accept: application/json' \
-H 'X-API-KEY: xxx'

HTTP GET Example URLs

Filter: https://database.massobs.org.uk/api/filter/?filter=gender&X-API-KEY=xxxx&accept=application/json

Search: https://database.massobs.org.uk/api/search/?gender=1&X-API-KEY=xxxx&accept=application/json

Licence

This database contains narratives written for the Mass-Observation Archive and to be used by those researching everyday life in Britain. The material is made available under a Creative Commons Attribution-Non Commercial 4.0 International (CC BY-NC 4.0) licence. Visit the Creative Common's website for more information [https://creativecommons.org/licenses/by-nc/4.0/].

By downloading these narratives, you are agreeing to uphold the nature of this licence.

The narratives may be used for non-commercial activities, such as teaching, student essays and private research as long as it is credited to the Mass-Observation Archive with the documents' reference. For all other usages please contact the Mass-Observation Archive for more details (moa@sussex.ac.uk).

Permission to use third-party material found in the documents needs to be sought separately.

This work is licensed under CC BY-NC 4.0