Ocean Scan API

Version 0.10 (30/11/2021)

Base URL: https://api-test.oceanscan.org

Authentication

Except where otherwise noted, all calls to the Ocean Scan API require authentication, provided by Firebase Authentication. API clients can use one of the available versions of the Firebase Authentication client: iOS, Android, web/Node.js (firebase module in npm), C++, Unity.

To configure Firebase Authentication for Ocean Scan:

const firebase = require('firebase');
firebase.initializeApp({
  apiKey: 'AIzaSyDyUaGKsDF4ehNynckdKUXs5nzI6HZnF94',
  authDomain: 'global-plastic-db.firebaseapp.com',
  databaseURL: 'https://global-plastic-db.firebaseio.com',
  projectId: 'global-plastic-db',
  storageBucket: 'global-plastic-db.appspot.com',
  messagingSenderId: '1051434574176',
  appId: '1:1051434574176:web:e6885bee2539073c093e05',
});

To sign in, use the email and password method:

const auth = firebase.auth();
await auth.signInWithEmailAndPassword(email, password);

After sign-in, you’ll need an ID token to use the Ocean Scan API:

const token = await auth.currentUser.getIdToken();

Tokens are short-lived (1 h), so make sure to get a new token before the old one expires. There are multiple ways to do it, but probably the simplest one is to force generation of a new token with a periodicity slightly below 1 h:

setInterval(async () => {
  const token = await auth.currentUser.getIdToken(true);
  /* store in local state... */
}, 55 * 60e3);

Make sure to include a valid ID token in the Authorization header of all calls to the API:

Authorization: Bearer <token>

API responses

JSON is used in the body of API requests and responses. Errors returned by the API are also in JSON format.

Successful requests return a 200 status code. The response body is formatted in JSON and has the form:

• Singular endpoints (e.g. /api/:version/me):

  {
    "result": {
      // ...
    }
  }

• Plural endpoints (e.g. /api/:version/litterTypes):

  {
    "results": [
      {
        // ...
      },
      {
        // ...
      },
      {
        // ...
      }
    ]
  }

Failed requests return a status code following convention (3xx for redirections, 4xx for client errors, 5xx for server errors). The response body is formatted in JSON and has the form:

{
  "errorHttpStatusCode": 400,
  "errorCode": "INVALID_QUERY",
  "errorDescription": "Query parameter `after` does not look like a valid date/datetime"
}

Endpoint versions

Most endpoint URLs have the form /api/:version/.... The version parameter is related to a set of guaranteed query parameters and result attributes. Legal version values and whether they are deprecated are included in the endpoint documentation.

New query parameters or result attributes may be added without affecting the endpoint version, but not removed. Versions -v0 are an exception to this rule.

Note: The general Ocean Scan API version (X.Y) may change due to bug fixes or additional response attributes without affecting endpoint versions.

Sorting results

For endpoints that support sorting, the following query parameters can be used to specify the sort order:

• sort: attribute used for sorting
• descending: when enabled (anything other than 0 or false), sets the sort order to descending rather than ascending

Example: GET /api/:version/campaigns?sort=tSort&descending=false: sort by tSort in descending order

Pagination

For endpoints that support pagination, the following query parameters can be used to modify the result set:

• count: number of items to be returned (by default, 20)
• cursor: opaque string provided by the API in a prior call, indicating the first item in the page to be returned

For instance, if we query GET /api/:version/campaigns, the API will respond with something like:

{
  "nextPage": "dFNvcnQvMS8xNjM2NDM5Njk1Njcy",
  "results": [
    // ... 20 results ...
  ]
}

We can fetch the next page of results using the cursor from the previous request: GET /api/:version/campaigns?cursor=dFNvcnQvMS8xNjM2NDM5Njk1Njcy.

The last page of results will look like this:

{
  "nextPage": null,
  "results": [
    // ... results ...
  ]
}

Important note: a cursor can only be used with the same sort and descending parameters with which it was created, for instance:

• GET /api/:version/campaigns?descending=false returns "nextPage": "dFNvcnQvMC8xNTkxOTY5OTM4MDEy"
• GET /api/:version/campaigns?descending=false&cursor=dFNvcnQvMC8xNTkxOTY5OTM4MDEy returns the next page of results

• GET /api/:version/campaigns?cursor=dFNvcnQvMC8xNTkxOTY5OTM4MDEy uses a different sort order and will result in an error:

  {
    "errorHttpStatusCode": 400,
    "errorCode": "INVALID_CURSOR",
    "errorDescription": "Invalid `cursor` for the selected `sort` and `descending` query attributes"
  }

Using a cursor on a different found set (e.g. filtering campaigns with before or after) will not result in an error, but may lead to unexpected results.

Authorised operations

Campaigns: general rules

• A closed Campaign (isClosed: true) cannot be modified. Modifications include non-read operations on the Campaign itself, or on any of its associated data (Observations, Measurements, Images).
• A closed Campaign (isClosed: true) cannot be reopened. This rule might be revised in the future.
• A Campaign can only be deleted by its creator.
• A Campaign can only be closed by its creator.
• A Campaign can be modified by a User only if the User is a Campaign Participant. Modifications include non-read operations on the Campaign itself, or on any of its associated data (Observations, Measurements, Images).
• A Campaign can be read by all Users.
• A Campaign’s associated data (Observations, Measurements, Images) can be read by a User only if the User is a Campaign Participant or the Campaign is public (isDataPublic: true).

Campaign Participations: joining or leaving a Campaign

• The list of Campaign Participations can be read by all Users.
• A Campaign Participant can create a Campaign Participation for any other User of the system.
• A Campaign Participant can delete her Campaign Participation.
• A Campaign’s creator can delete Campaign Participations from her Campaign.

Campaign-less Observations

• Campaign-less Observations can be read by any User.
• Campaign-less Observations can be created/updated/deleted only by the Observation’s creator.

The above rules also apply to reads/writes on Measurements and Images associated to the Observation.

Users

• Users can only be created/modified/deleted by themselves.

Other API aspects

All dates are formatted in ISO8601, UTC time.

Entities and endpoints

Users

GET /api/:version/me

Returns the currently logged-in User.

Versions: dca-v0, web-v0

Query options: none.

GET /api/:version/user/:id

Returns a User by ID.

Versions: dca-v0, web-v0

Query options: none.

POST /api/:version/user

Creates a User. User must provide the new User’s ID (a UUID v4) in the request body. The request’s id and email must match the authenticated person’s ID and email address, respectively.

Versions: dca-v0, web-v0

Query options: none.

PATCH /api/:version/user/:id

Updates a User. User must provide only the parameters to be updated.

Versions: dca-v0, web-v0

Query options: none.

DELETE /api/:version/user/:id

Deletes a User by ID. Returns an empty payload.

Versions: dca-v0, web-v0

Query options: none.

GET /api/:version/userByEmail/:email

Returns a User by email (useful for adding Users to a Campaign).

Versions: dca-v0, web-v0

Query options: none.

Campaigns

A Campaign is a group of Observations that form a logical group: carried out by the same team, over the same approximate area, over a certain time interval. Datasets are also modelled as Campaigns.

General extra attributes:

• vehicleType (string, e.g. vessel, submersible, drone…)
• vehicleName (string)

Specific beach-related extra attributes, only applicable when environmentalCompartments includes ‘BEACH’ (https://beachlitter.ospar.org/):

• name
• type (comma-separated list of: {sand, rock…} and %coverage)
• topography (flat, slight slope, medium slope, or %…)
• usage (comma-separated list of: fishing, swimming, board sports…)
• access (comma-separated list of: pedestrian, vehicle…)
• backOfBeach (comma-separated list of: dunes, woods, …)
• widthMinM (number)
• widthMaxM (number)
• lengthM (number)
• facingDeg (number, from N, clockwise)
• prevailingWindDeg (number, from N, clockwise)
• developmentBehind (boolean)
• foodDrinkOutlets (boolean)
• nearestTownKm (number)
• nearestRiverMouthKm (number)
• nearestHarbourKm (number)
• nearestShippingLaneKm (number)
• nearestShippingLaneShipYear (number)
• nearestWaste_waterDischargeKm (number)
• cleaning (text)

GET /api/:version/campaigns

Returns the Campaigns where the User is a participant. When onlyMine is set to false, this endpoint returns all Campaigns.

Versions: dca-v0, web-v0

Query options:

GET /api/:version/campaign/:id

Returns a Campaign by ID.

No authentication needed.

Versions: dca-v0, web-v0

Query options: none.

POST /api/:version/campaign

Creates a Campaign. User must provide the new Campaign’s ID (a UUID v4) in the request body.

Versions: dca-v0, web-v0

Query options: none.

PATCH /api/:version/campaign/:id

Updates a Campaign. User must provide only the parameters to be updated.

Versions: dca-v0, web-v0

Query options: none.

DELETE /api/:version/campaign/:id

Deletes a Campaign by ID. Returns an empty payload.

Versions: dca-v0, web-v0

Query options: none.

POST /api/:version/campaign/:id/close

Closes a Campaign by ID and publishes its data on Zenodo. Returns the updated Campaign. Notes:

• A Campaign can only be closed if it’s open.
• Once closed, a Campaign cannot be re-opened. This may change in the future.
• Closed Campaigns and their associated data (Observations, Measurements, Images) cannot be modified.

Versions: dca-v0, web-v0

Query options: none.

Campaign Participations

A Campaign Participation represents the link between a User and a Campaign.

Legal values for role: ContactPerson, DataCollector, DataCurator, DataManager, Distributor, Editor, Funder, HostingInstitution, Producer, ProjectLeader, ProjectManager, ProjectMember, RegistrationAgency, RegistrationAuthority, RelatedPerson, Researcher, ResearchGroup, RightsHolder, Supervisor, Sponsor, WorkPackageLeader, AllianceMember, Other.

GET /api/:version/campaignParticipations

Returns the Campaign Participations for a given Campaign (mandatory campaignId query parameter, see below). Campaign Participations are always returned sorted by createdAt, in ascending order, and include relevant User information.

Versions: dca-v0, web-v0

Query options:

GET /api/:version/campaignParticipation/:id

Returns a Campaign Participation by ID.

Versions: dca-v0, web-v0

Query options: none.

POST /api/:version/campaignParticipation

Creates a Campaign Participation. User must provide the new Campaign Participation’s ID (a UUID v4) in the request body. The User’s affiliation is copied to the new record, but can be modified afterwards.

Versions: dca-v0, web-v0

Query options: none.

PATCH /api/:version/campaignParticipation/:id

Updates a Campaign Participation. User must provide only the parameters to be updated.

Versions: dca-v0, web-v0

Query options: none.

DELETE /api/:version/campaignParticipation/:id

Deletes a Campaign Participation by ID. Returns an empty payload.

Versions: dca-v0, web-v0

Query options: none.

Observations

An Observation represents a ground-truth information unit, taken at a given time at a certain place (geometry). An Observation can be positive (existence of marine litter) or negative (absence). An Observation may have multiple associated Images, as well as multiple associated Measurements. Its key attributes include a geometry and a timestamp.

An Observation may or may not belong to a Campaign: there are campaign-less Observations.

sourceType values (multiple values possible):

• Vehicle type: NO_VEHICLE, GROUND, WATERCRAFT, AIRCRAFT, SATELLITE, ...
• Vehicle details: BOAT, SUBMARINE, DRONE, PLANE, LEO, MEO, ...
• Sensor type: HUMAN, OPTICAL, SAR, ...

validationType values (multiple values possible):

• IN_SITU
• CONCLUSIVE_HIRES_SATELLITE_IMAGE
• INCONCLUSIVE_HIRES_SATELLITE_IMAGE
• ...

extra attributes:

• waveStatus: qualitative (rough, calm...) or significant wave height (SWH, in m)
• wind: qualitative (very strong, strong, calm...) or speed (m/s)
• illumination: TBD

GET /api/:version/observations

Returns the Observations for a given Campaign (mandatory campaignId query parameter, see below). Observations are always returned sorted by timestamp, in descending order.

Versions: dca-v0, web-v0

Query options:

POST /api/:version/observations/find

Returns a set Observations matching all (AND) the criteria specified in the request body. For criteria accepting multiple values (arrays), all values are accepted (OR). Observations are always returned sorted by timestamp, in descending order.

Note that some observations are not visible by some users. This happens for instance when the corresponding Campaign has isDataPublic set to false and the user is not a participant of the Campaign.

Public: yes. Authentication is optional, but it may increase the number of observations that the user can find (see above).

Versions: dca-v0, web-v0

Body (JSON):

GET /api/:version/observation/:id

Returns an Observation by ID.

Versions: dca-v0, web-v0

Query options: none.

POST /api/:version/observation

Creates an Observation. User must provide the new Observation’s ID (a UUID v4) in the request body.

Versions: dca-v0, web-v0

Query options: none.

PATCH /api/:version/observation/:id

Updates an Observation. User must provide only the parameters to be updated.

Versions: dca-v0, web-v0

Query options: none.

DELETE /api/:version/observation/:id

Deletes an Observation by ID. Returns an empty payload.

Versions: dca-v0, web-v0

Query options: none.

Measurements

A Measurement represents a quantity of marine litter of a given type (including G999 - Unidentified and G998 - Mixed).

A Measurement belongs to an Observation.

Notes (in accordance with the JRC guide on marine litter):

• Mixed materials/types: use G998 - Mixed.
• Single but non-identified/unrecognisable materials/types: use G999 - Unidentified or NULL.
• All pieces of litter that are recognisable as an item: use quantity 1.
• Pieces of plastic which are not recognisable as an item: use G76 - plastic pieces 2.5-50 cm.
• Pieces of plastic that are recognisable as a (shopping) bag: use G3 - Shopping bags incl. pieces.
• Pieces of plastic that are recognisable as a small plastic bag: use G4 - Small plastic bags, e.g. freezer bags, incl. pieces.
• All pieces that are recognisably part of a balloon (including the plastic valves, the plastic ribbons or string tied to the balloon): use G125 - Balloons, balloon sticks.
• Pieces of glass that are recognisable as for example bottles: use G200 – Bottles incl. pieces.
• Pieces of glass that are not recognisable as an item: use G208 - Glass or ceramic fragments >= 2.5 cm.
• All pieces of string and cord: use G50 – String and cord (diameter < 1 cm) with quantity 1.

GET /api/:version/measurements

Returns the Measurements for a given Observation (mandatory observationId query parameter, see below). Measurements are always returned sorted by createdAt, in ascending order.

Versions: dca-v0, web-v0

Query options:

GET /api/:version/measurement/:id

Returns a Measurement by ID.

Versions: dca-v0, web-v0

Query options: none.

POST /api/:version/measurement

Creates a Measurement. User must provide the new Measurement’s ID (a UUID v4) in the request body.

Versions: dca-v0, web-v0

Query options: none.

PATCH /api/:version/measurement/:id

Updates a Measurement. User must provide only the parameters to be updated.

Versions: dca-v0, web-v0

Query options: none.

DELETE /api/:version/measurement/:id

Deletes a Measurement by ID. Returns an empty payload.

Versions: dca-v0, web-v0

Query options: none.

Images

An Image represents a user-uploaded photo and is associated to an Observation.

Note: after an image is uploaded, it can take up to a few minutes (typically just a few seconds) for the image to be processed, after which its url becomes available.

POST /api/:version/image

Creates an Image. User must provide the new Measurement’s ID (a UUID v4) in the request body.

Versions: dca-v0, web-v0

Query options: none.

Important notes:

The request must be sent as a multipart form (Content-Type: multipart/form-data) with the following mandatory fields:

• id
• creatorApp
• measurementId
• image: the binary image data

Also note:

• The image part must include filename (e.g. test.jpg) and Content-Type (e.g. image/jpeg).
• Valid MIME types include image/jpeg, image/png, image/gif, image/webp. All files will be processed by the back-end and converted to JPEG before adding it to the Ocean Scan data lake.
• Maximum file size is approximately 4 MB.

DELETE /api/:version/image/:id

Deletes an Image by ID. Returns an empty payload.

Versions: dca-v0, web-v0

Query options: none.

Matching EO Product

A Matching EO Product represents a certain EO (imagery) product that has been matched to an Observation.

meta attributes depend on the product (platformName, sensorName, productType), but typically include:

• externalId: granule ID used by the external data provider, e.g. Copernicus Hub
• sizeMB: granule size in MB
• filename
• orbitDirection: ascending or descending
• orbitNumber
• relativeOrbitNumber
• cloudCoverPercentage

GET /api/:version/matchingEoProducts

Returns the Matching EO Products for a given Observation (mandatory observationId query parameter, see below). Matching EO Products are always returned sorted by createdAt, in ascending order.

Versions: dca-v0, web-v0

Query options:

GET /api/:version/matchingEoProduct/:id

Returns a Matching EO Product by ID.

Versions: dca-v0, web-v0

Query options: none.

Litter types

A Litter Type is a standardised class assigned to a Measurement. Please refer to the JRC guide on marine litter for more details.

GET /api/:version/litterTypes

Versions: dca-v0, web-v0

Query options: none.