Documentation of the TOARDB FastAPI REST interface

A Representational State Transfer (REST) service allows querying all data and analysis products from the Tropospheric Ozone Assessment Report (TOAR) database of surface ozone observations.

This documentation describes the URL architecture and query options of the TOAR REST interface. For general information on REST, please consult other resources.

Table of Contents

1. General

1.1 Base URL

https://toar-data.fz-juelich.de/api/v2/analysis/

Response: Description and documentation of available REST services (this document)

1.2 Services

The following information services are available and described individually below. Each service is invoked by appending its name and possible query arguments to the base URL.

  • data: get data from one or more time series

  • statistics: get aggregated data from one or more time series

1.3 Query arguments

In order to control the database queries and hence the response of the TOAR REST service, you can add arguments to the service URL. These arguments must adhere to the format argumentname=value. The first argument is prepended by a ? character, all other arguments are separated by & characters.

1.4 Response format

Currently, only zip archives containing files formatted in csv are supported.

1.5 Error messages

The REST service may return a page with error code 500 if you try to open a malformed URL. Usually, a meaningful error message shall be returned in this case.

Note that queries which are formally correct, but return no results, return a valid page (HTML code 204) with corresponding message.

2. Description of services

2.1 Data

https://toar-data.fz-juelich.de/api/v2/analysis/data/timeseries/[?QUERY-OPTIONS]

where QUERY-OPTIONS are:

any combination of query options from both Stationmeta and Timeseries

Response: A zip archive containing the data of the requested records.

2.2 Statistics

https://toar-data.fz-juelich.de/api/v2/analysis/statistics/[?QUERY-OPTIONS]

where QUERY-OPTIONS are:

any combination of query options from both Stationmeta and Timeseries
sampling=(daily|monthly|seasonal|vegseason|summer|xsummer|annual)
metrics=any number of defined metrics
seasons=seasons to use for seasonal metrics
crops=crops to use for vegseason metrics
data_capture=fraction of available data to return a value in the aggregated time period

Response: A zip archive containing the aggregated data of the requested records.