1.1 Base URL

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

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.

• ontology: query the used ontology of the database

• controlled_vocabulary: query the controlled vocabulary and their description from the database

• variables: query variables and their metadata from the database

• stationmeta: query station ids, station names, and station location from the database

• timeseries: query the data series id and specific metadata of a series from the database

• search: query that combines the above services for stationmeta and timeseries

• data: get data from one timeseries

• geopeas_urls: show how we use the geopeas services to enriche our stations metadata

• database_statistics: show database statistics (number of users, stations, timeseries, data records

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

The default response format is json. You can control the format with the format= option in the data and ontology queries. Currently, only json, csv, and html are supported.

2.1 Ontology

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

where QUERY-OPTIONS are:

format = (xml|owldoc)

Response: By default, the query will return the ontology in xml format.

Example: https://toar-data-dev.fz-juelich.de/api/v2/ontology?format=xml

2.2 Controlled Vocabulary

https://toar-data-dev.fz-juelich.de/api/v2/controlled_vocabulary/[name]

If no name is given, the complete controlled vocabulary is returned.

Valid names are:
Role Code
Role Status
Kind Of Annotation
Kind Of Organization
Sampling Frequency
Aggregation Type
Data Origin Type
Data Origin
Climatic Zone 2019
Country Code
Timezone
Station Coordinate Validity
Station Type
Station Type Of Area
Station TOAR Category
Station HTAP Region
Station Landcover Type
Station ECO Region Type
Result Type
Data Flag
Type Of Change

Example: https://toar-data-dev.fz-juelich.de/api/v2/controlled_vocabulary/Station Type

Result:

[[0,”Unknown”,”unknown”],[1,”Background”,”background”],[2,”Traffic”,”traffic”],[3,”Industrial”,”industrial”]]

2.3 Variables

https://toar-data-dev.fz-juelich.de/api/v2/variables/[name][?QUERY-OPTIONS]
or
https://toar-data-dev.fz-juelich.de/api/v2/variables/id/[id][?QUERY-OPTIONS]

where QUERY-OPTIONS are:

limit= <integer: count> (default: 10)
offset= <integer: number of elements to be skipped> (default: 0)

To get a list of all available variables use limit=None.

Response: Each query result consists of all fields of station metadata.

If no name is given, 10 variables will be returned (ordered by their internal id).

The second query format using a variable id, works only with a given id.

Example: https://toar-data-dev.fz-juelich.de/api/v2/variables/o3

Result:

{“name”:”o3”,”longname”:”ozone”,”displayname”:”Ozone”,”cf_standardname”:”mole_fraction_of_ozone_in_air”,”units”:”nmol mol-1”,”chemical_formula”:”O3”,”id”:5}

2.4 Stationmeta

https://toar-data-dev.fz-juelich.de/api/v2/stationmeta/[name][?QUERY-OPTIONS]
or
https://toar-data-dev.fz-juelich.de/api/v2/stationmeta/id/[id][?QUERY-OPTIONS]

where QUERY-OPTIONS are:

To get a list of all available stations use limit=None.

Response: Each query result, unless fields= is used, consists of all fields of station metadata.

If no no name is given, 10 stations will be returned (ordered by their internal id).

The second query format using a station id, works only with a given id.

Example: https://toar-data-dev.fz-juelich.de/api/v2/stationmeta/CPT134S00

Result:

[{“id”:2,”codes”:[“CPT134S00”],”name”:”Cape Point”,”coordinates”:{“lat”:-34.35,”lng”:18.48,”alt”:230.0},”coordinate_validation_status”:”not checked”,”country”:”South Africa”,”state”:”Western Cape”,”type_of_environment”:”background”,”type_of_area”:”rural”,”timezone”:”Africa/Johannesburg”,”additional_metadata”:{},”roles”:[],”annotations”:[],”aux_images”:[],”aux_docs”:[],”aux_urls”:[],”globalmeta”:{“population_density_year2010”:-1.0,”max_population_density_25km_year2010”:-1.0,”climatic_zone_year2016”:”warm temperate dry”,”nightlight_1km_year2013”:-999.0,”nightlight_5km_year2013”:-999.0,”max_nightlight_25km_year2013”:-999.0,”wheat_production_year2000”:-999.0,”rice_production_year2000”:-999.0,”edgar_htap_v2_nox_emissions_year2010”:-999.0,”omi_no2_column_years2011to2015”:-999.0,”htap_region_tier1”:”-1 (undefined)”,”etopo_alt”:-999.0,”etopo_min_alt_5km”:-999.0,”etopo_relative_alt”:-999.0,”dominant_landcover_year2012”:”-1 (undefined)”,”toar1_category”:”unknown”,”station_id”:2},”changelog”:[]}]

Example: https://toar-data.fz-juelich.de/api/v2/stationmeta/?bounding_box=49.2,7.0,50.1,8.1&limit=None

Result: (extremly shrinked: all metadata of stations that fall into the defined rectangle are returned!)

[{“id”:188,”codes”:[“DERP014”],”name”:”Hunsrück-Leisel”,
…
”changelog”:[{“datetime”:”2021-08-31T13:13:51.621321+00:00”,”description”:”station created”,”old_value”:””,”new_value”:””,”station_id”:3865,”author_id”:1,”type_of_change”:”created”},{“datetime”:”2022-02-04T22:07:40.557614+00:00”,”description”:”add climatic_zone_year2016 from geopeas service”,”old_value”:”{‘climatic_zone_year2016’: ‘Undefined’}”,”new_value”:”{‘climatic_zone_year2016’: ‘WarmTemperateDry’}”,”station_id”:3865,”author_id”:1,”type_of_change”:”single value correction in metadata”},{“datetime”:”2022-04-14T16:49:28.608142+00:00”,”description”:”add country from OSM nominatim (HIFIS instance)”,”old_value”:”{‘country’: ‘N/A’}”,”new_value”:”{‘country’: ‘DE’}”,”station_id”:3865,”author_id”:1,”type_of_change”:”single value correction in metadata”},{“datetime”:”2022-04-14T16:49:28.648002+00:00”,”description”:”add htap_tier1_region from GEO PEAS”,”old_value”:”{‘htap_region_tier1_year2010’: ‘HTAPTier1Undefined’}”,”new_value”:”{‘htap_region_tier1_year2010’: ‘HTAPTier1EUR’}”,”station_id”:3865,”author_id”:1,”type_of_change”:”single value correction in metadata”}]}]

2.5 Timeseries

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

where QUERY-OPTIONS are:

To get a list of all available time series use limit=None.

Response: Each query result, unless fields= is used, consists of all fields of time series metadata.

If no QUERY-OPTIONS are given, 10 random time series will be returned.

Example: https://toar-data-dev.fz-juelich.de/api/v2/timeseries/?limit=1

Result:

[{“id”:25,”label”:””,”order”:1,”access_rights”:”by attribution”,”sampling_frequency”:”hourly”,”aggregation”:”mean”,”data_start_date”:”2009-01-01T00:00:00+00:00”,”data_end_date”:”2010-12-31T23:00:00+00:00”,”data_origin”:”ERA 5”,”data_origin_type”:”model”,”version”:””,”data_license_accepted”:”1900-01-01T00:00:00+00:00”,”sampling_height”:2.0,”additional_metadata”:{},”station”:{“id”:1021,”codes”:[“in_gad1379”],”name”:”Gadanki”,”coordinates”:{“lat”:13.45,”lng”:79.18,”alt”:360.0},”coordinate_validation_status”:”not checked”,”country”:”India”,”state”:”Andhra Pradesh”,”type_of_environment”:”background”,”type_of_area”:”rural”,”timezone”:”Asia/Kolkata”,”additional_metadata”:{}},”variable”:{“name”:”humidity”,”longname”:”atmospheric humidity”,”displayname”:”Humidity”,”cf_standardname”:”specific_humidity”,”units”:”g kg-1”,”chemical_formula”:””,”id”:32},”programme”:{“id”:0,”name”:”None”,”longname”:””,”homepage”:””,”description”:””},”roles”:[],”annotations”:[],”changelog”:[]}]

Example: https://toar-data-dev.fz-juelich.de/api/v2/timeseries/25/

Result:

[{“id”:25,”label”:””,”order”:1,”access_rights”:”by attribution”,”sampling_frequency”:”hourly”,”aggregation”:”mean”,”data_start_date”:”2009-01-01T00:00:00+00:00”,”data_end_date”:”2010-12-31T23:00:00+00:00”,”data_origin”:”ERA 5”,”data_origin_type”:”model”,”version”:””,”data_license_accepted”:”1900-01-01T00:00:00+00:00”,”sampling_height”:2.0,”additional_metadata”:{},”station”:{“id”:1021,”codes”:[“in_gad1379”],”name”:”Gadanki”,”coordinates”:{“lat”:13.45,”lng”:79.18,”alt”:360.0},”coordinate_validation_status”:”not checked”,”country”:”India”,”state”:”Andhra Pradesh”,”type_of_environment”:”background”,”type_of_area”:”rural”,”timezone”:”Asia/Kolkata”,”additional_metadata”:{}},”variable”:{“name”:”humidity”,”longname”:”atmospheric humidity”,”displayname”:”Humidity”,”cf_standardname”:”specific_humidity”,”units”:”g kg-1”,”chemical_formula”:””,”id”:32},”programme”:{“id”:0,”name”:”None”,”longname”:””,”homepage”:””,”description”:””},”roles”:[],”annotations”:[],”changelog”:[]}]

2.6 Search (combined endpoint of stations and timeseries)

This endpoint enables queries that filter for a combination of metadata of stations and timeseries.
Any combination of query options (except for id) from both 2.4 Stationmeta and 2.5 Timeseries is possible here.

Response: Each query result, unless fields= is used, consists of all fields of time series metadata.

If no QUERY-OPTIONS are given, 10 random time series will be returned.

Example from the TOAR Quick Start Guide:
https://toar-data.fz-juelich.de/api/v2/search/?bounding_box=49,7,50,8&variable_id=5,4&limit=None

The above command will get you all the time series within an area between 49°N 7°E and 50°N 8°E that record ozone or pm1.

2.7 Data

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

where QUERY-OPTIONS are:

limit= <integer: count> (default: 10; if using format=csv, the limit option will be ignored)
format = (json|csv)

Response: Each record of the query result consists of the fields datetime, value, flags, timeseries_id, version.

If no QUERY-OPTIONS are given, 10 random data entries will be returned.

Example: https://toar-data-dev.fz-juelich.de/api/v2/data/timeseries/52

Result:

[{“datetime”:”2009-01-01T00:00:00+00:00”,”value”:0.0,”flags”:”OK validated verified”,”timeseries_id”:52,”version”:”000001.000000.00000000000000”},{“datetime”:”2009-01-01T01:00:00+00:00”,”value”:0.0,”flags”:”OK validated verified”,”timeseries_id”:52,”version”:”000001.000000.00000000000000”},…,{“datetime”:”2010-12-31T21:00:00+00:00”,”value”:0.0,”flags”:”OK validated verified”,”timeseries_id”:52,”version”:”000001.000000.00000000000000”},{“datetime”:”2010-12-31T22:00:00+00:00”,”value”:0.0,”flags”:”OK validated verified”,”timeseries_id”:52,”version”:”000001.000000.00000000000000”},{“datetime”:”2010-12-31T23:00:00+00:00”,”value”:0.0,”flags”:”OK validated verified”,”timeseries_id”:52,”version”:”000001.000000.00000000000000”}]

Example: https://toar-data-dev.fz-juelich.de/api/v2/data/timeseries/52?format=csv

Result:A file containing the comma separated values of the requested time series

2.8 Contact information

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

https://toar-data-dev.fz-juelich.de/api/v2/contacts/id/[id]

https://toar-data-dev.fz-juelich.de/api/v2/contacts/persons/[name]

https://toar-data-dev.fz-juelich.de/api/v2/contacts/persons/id/[id]

https://toar-data-dev.fz-juelich.de/api/v2/contacts/organisations/[name]

https://toar-data-dev.fz-juelich.de/api/v2/contacts/organisations/id/[id]

2.9 GeoPEAS URLs

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

This shows how we use the geopeas services to enriche our stations metadata.

2.10 Database statistics

https://toar-data-dev.fz-juelich.de/api/v2/database_statistics/[name]

If no name is given, the complete database statistics is returned.

Valid names are:
users
stations
time-series
data records

Example: https://toar-data-dev.fz-juelich.de/api/v2/database_statistics/

Result:

{“users”:0,”stations”:13752,”time-series”:24891,”data records”:768839744}