O2A Documentation

Deprecated API (version 1) will be shut down ​

REGISTRY offers a universally applicable RESTful API to automate all kinds of workflows. Its swagger is available via https://registry.o2a-data.de/api/.

As REGISTRY is the successor of sensor.awi.de the outdated API endpoints from sensor.awi.de are still available in REGISTRY's API, referred to as API version 1 (APIv1).

This will change in near future. These APIv1 endpoints will be shut down latest by March 31st, 2025. So please, if not happened yet, start migrating your scripts/programms to use the new API (APIv2) exclusively.

If not sure you can distinct between the new API endpoints (APIv2) and the old ones by the link.

In the swagger the outdated endpoints are in parts already marked as deprecated.

APIv1 swagger

REGISTRY's new API deviates in concept and style from APIv1. This is caused by the updated data model of REGISTRY, a stricter commitment to the principles of HTTP requests, with fewer and condensed but yet comprehensible and fully operational endpoints, and a wider field of applications in mind.

All the functionality of the APIv1 endpoints is incorporated in the new API version 2 (APIv2) -- and beyond.

Here are some examples.

powerful RSQL statements ​

REGISTRY APIv2 comes along with the possibility to apply powerful filters and pre-selection statements by RSQL, read more about here, here, or here.

While

bash
https://registry.o2a-data.de/rest/v2/items

returns a (rather) long list of all items in REGISTRY, the return can be filtered by the where statement in the API call. In this case the known urn of an item can be used to retrieve a complete info dump about it.

bash
https://registry.o2a-data.de/rest/v2/items?where=code==vessel:mya_ii

This can be expanded by the with statement, e.g. to get information about all subitems,

bash
https://registry.o2a-data.de/rest/v2/items?where=code==vessel:mya_ii&with=children

all contacts,

bash
https://registry.o2a-data.de/rest/v2/items?where=code==vessel:mya_ii&with=contacts

or all resources available and its subitems

bash
https://registry.o2a-data.de/rest/v2/items?where=code==vessel:mya_ii&with=resources,children

specific endpoints turn generic ​

In APIv1 certain endpoints existed that had specifically one purpose exclusively. For example getSensorOutputByUrn was one of such.

Its only purpose was to derive the parameter output from a certain urn, such as station:heluwobs:heluw1:sbe38_awi_0659:temperature.

Nowadays, and more generically, this could be done by a sequence of APIv2 calls. Here, we show two (possible) examples to do that using python and R.

python
import requests
import json

def getSensorOutputByUrn(code):
    """"""
    registryUrl = "https://registry.o2a-data.de/rest/v2/items"
    parameter = code[::-1].split(':')[0][::-1]
    item = ":".join(code.split(':')[0:len(code.split(':'))-1])
    url = registryUrl + "?where=code==" + item
    itemFull = json.loads(requests.get(url).content)['records']
    itemId = itemFull[0]['id']
    url = registryUrl + "/" + str(itemId) + "/parameters?where=shortName==" + parameter
    parameterFull = json.loads(requests.get(url).content)['records']
    return(parameterFull)
R
library(jsonlite)

getSensorOutputByUrn  <- function(code){
    registryUrl <- "https://registry.o2a-data.de/rest/v2/items"
    seps <- unlist(strsplit(code, split = ':'))
    parameter <- seps[length(seps)]
    item <- paste(seps[1:length(seps)-1], collapse = ":")
    url <- paste0(registryUrl, "?where=code==" ,item)
    itemFull <- fromJSON(url)$records
    itemId <- itemFull$id
    url <- paste0(registryUrl, "/", itemId, "/parameters?where=shortName==", parameter)
    parameterFull <- fromJSON(url)$records
    return(parameterFull)
}