Application Programming Interface (API v1.0) Tutorial

The EMSO-ERIC machine-to-machine interface provides programmatic access to EMSO ERIC data and metadata via a Swagger-based RESTful Application Programming Interface (API). This interface allows authenticated users to access EMSO ERIC data and metadata through JSON-based requests.

unsplash-logo Tomoe Steineck

Full documentation of the API is undergoing; however, there are existing examples to assist in getting started using the API. The example below is not comprehensive, but it includes some step-by-step instructions and sample code that can be modified to request the data of interest.

Simple EMSO ERIC API Example using cURL

The examples below use the "cURL" command; however other mechanisms can be used such as specific libraries or a simple web browser.

1. API User Login Information

Before you can use the EMSO ERIC API, you need to obtain a account by sending an mail to help@emso-eu.org with subject “EMSO ERIC API registration” and the following information:

The EMSO ERIC support team will provide you with the password to be used on the API authentication process.

2. Authentication process

The following request provides a valid token given a valid combination of email and password. The token is refreshed every time this request is executed.

curl -X POST "http://api.emso.eu/auth/login" -H "Content-Type: application/json" -d "{ \"email\": \"WRITE_HERE_YOUR_EMAIL\", \"password\": \"WRITE_HERE_YOUR_PASSWORD\"}"

You will get a response with the authentication token.

{
  "status": "success",
  "message": "Successfully logged in.",
  "Authorization": "YOUR_TOKEN"
}

3. POST a metadata search query

The following request provides the metadata information associated with the datasets available in the system. In this case, we are going to obtain the metadata ID of the observatories of the EMSO site "Ligurian":

curl --location --request POST 'http://api.emso.eu/metadata/' \
--header 'Authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
 "site": ["ligurian"],
 "_source": ["id"]}'

The response:

{
 "status": true,
 "result": [
  {"id": "OS_DYFAMED_1995_FCO2TW"},
  {"id": "MO_TS_MO_W1M3A"},
  {"id": "DYF_SBE2009-2010"},
  {"id": "GL_TS_MO_ANTARES"}]}

With the following request users can obtain metadata information for id "GL_TS_MO_ANTARES".

curl --location --request GET 'http://api.emso.eu/metadata/GL_TS_MO_ANTARES' \
--header 'Authorization: YOUR_TOKEN'

The response:

{
 "status": true,
 "result": {
  "data_type": "OceanSITES time-series data",
  "format_version": "1.2",
  "platform_code": "ANTARES",
  "date_update": "2019-05-12T12:57:08Z",
  "institution": "Mediterranean Institute of Oceanography - La Seyne sur Mer (MIO)",
  "institution_edmo_code": "2975",
  "site_code": " ",
  "wmo_platform_code": "6801000",
  "coriolis_platform_code": "6801000",
  "platform_name": "Antares - ligne de mouillage",
  ...
}

3. POST a data search query

The following example provides sea water pressure data from "GL_TS_MO_ANTARES" from 2014.

curl --location --request POST 'http://api.emso.eu/data/' \
--header 'Authorization: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
 "parameters": ["PRES"],
 "time_min": "2014-01-01 00:00:00",
 "time_max": "2014-12-31 23:59:59",
 "metadata_ids": ["GL_TS_MO_ANTARES"]}'

The response:

{
 "status": true,
 "result": [
  {
   "parameter": "PRES",
   "time": "2014-01-22 14:20:23",
   "time_qc": 1,
   "depth": "2193.0",
   "depth_qc": 1,
   "value": "2193.0810546875",
   "value_qc": 0,
   "metadata_id": "GL_TS_MO_ANTARES"
  },
  ...
 ]}