Introduction

The OASIS REST API provides access to information about OASIS Projects via a RESTful API.

It is designed to provide programmatic access to OASIS Project information and its output is very similar to that of the existing "Export" function that can be found on the OASIS Projects list.

The base URL for the OASIS REST API is https://api.oasis.ac.uk/v1/

Authentication

To authenticate with the OASIS REST API, send an Authorization: Basic HTTP header with each request, containing a Base64 encoded email and password pair, separated by a semicolon.

Projects

You can request information about OASIS Projects using the https://api.oasis.ac.uk/v1/projects endpoint.

Specifying an OASIS Project ID e.g. https://api.oasis.ac.uk/v1/projects/oasis-project-123 will return information about that specific Project.

If you do not provide an OASIS Project ID then you must provide additional org_id and role parameters - the API will then return 10 projects per page, with the page number specified by the page parameter.

e.g. https://api.oasis.ac.uk/v1/projects?org_id=1000001&role=O1&page=1

A list of your organisations and their respective IDs can be obtained by making a request to the following endpoint, again with the Authorization: Basic HTTP header, as above.

https://api.oasis.ac.uk/v1/organisations

Valid values for the role parameter are listed below. Note: not every organisation has access to every role.

Role Description
O1 Researcher which submits OASIS forms (commercial data inputter)
O1a Community group which submits OASIS forms
O2 Historic Environment Record (regional reviewer)
O2a Other reviewing organisation
O3 Museum/Archive
O4 Organisation with responsibility for reviewing OASIS records nationally
O4a Discovery and Excavation in Scotland
O5 Organisation which needs to download completed OASIS records for analysis

Differences between REST API and Export

  • In the adminAreasMap section of the Export JSON the field names vary depending on the country within which the coordinates reside. They are named Former County vs County and Council vs District/Unitary Authority depending on whether the coordinates are in England or Scotland.

    In the REST API response, the fields are always named county and district for consistency and ease of consumption. There are now additional fields named countyLabel and districtLabel, the contents of which should be used to show the different labels for England and Scotland.

    All field names are now in camelCase.

  • Date fields no longer contain a default time of 12:00

Code Example

Below is a (server-side) JavaScript code example using Fetch.

const email = 'your@email.ac.uk';
const password = 'yourPassword';
const encodedPair = Buffer.from(`${email}:${password}`).toString('base64');

fetch('https://api.oasis.ac.uk/v1/projects/oasis-project-123', {
    headers: {
         Authorization: `Basic ${encodedPair}`) 
    }
})
.then(res => res.json())
.then(json => console.log(json));
API requests made from client-side JavaScript code will fail due to same-origin policy. This is to help avoid the exposure of user credentials in client-side code.

University of York Legal Statements