Documentation of the TOARDB FastAPI REST interface

A Representational State Transfer (REST) service allows querying all metadata and data 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

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

  • geolocation_urls: show how we use the geolocation 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.

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 200) with empty content. If the response format is json, you will typically receive an empty array [] in this case.

2. Description of services

2.1 Ontology

https://toar-data.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.fz-juelich.de/api/v2/ontology?format=xml

2.2 Controlled Vocabulary

https://toar-data.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 Dominant Landcover Type
Result Type
Data Flag
Type Of Change

Example: https://toar-data.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.fz-juelich.de/api/v2/variables/[name][?QUERY-OPTIONS]
or
https://toar-data.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)

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.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.fz-juelich.de/api/v2/stationmeta/[name][?QUERY-OPTIONS]
or
https://toar-data.fz-juelich.de/api/v2/stationmeta/id/[id][?QUERY-OPTIONS]

where QUERY-OPTIONS are:

Name Type Description
limit integer count (default: 10)
offset integer number of elements to be skipped (default: 0)
id integer internally (in the database) used id of the station
codes [ string ] list of station's codes
name string Station name for use in TOAR; normally equal to data provider’s name
basic similarity check, if given argument (case insensitive) is contained in station‘s name
bounding_box list of four numbers The bounding_box (min_lat, min_lon, max_lat, max_lon in degrees_north/degrees_east) define a geographical rectangle
altitude_range list of two numbers The given numbers define an altitude range (in m)
coordinate_validation_status string Flag indicating whether the location of a station has been verified (see controlled vocabulary: Coordinate Validity)
country string The country, where the station resides, or which operates the station (e.g. in Antarctica) (see controlled vocabulary: Country Code)
state string The state or province, where the station resides
type string Type of station (see controlled vocabulary: Station Type)
type_of_area string Type of station area (see controlled vocabulary: Station Type Of Area)
timezone string Station timezone (see controlled vocabulary: Timezone)
toar1_category string The station classification for the Tropsopheric Ozone Assessment Report based on the station proxy data that are stored in the TOAR database (see controlled vocabulary: Station TOAR Category)
station_id integer internal station_id to which these global data belong
climatic_zone_year2016 string value for the year 2016 of the following data:
units: -
data_source: University of East Anglia Climatic Research Unit; Harris, I.C.; Jones, P.D. (2017): CRU TS4.00: Climatic Research Unit (CRU) Time-Series (TS) version 4.00 of high-resolution gridded data of month-by-month variation in climate (Jan. 1901- Dec. 2015). Centre for Environmental Data Analysis, 25 August 2017. doi:10.5285/edf8febfdaad48abb2cbaf7d7e846a86. http://dx.doi.org/10.5285/edf8febfdaad48abb2cbaf7d7e846a86
citation: University of East Anglia Climatic Research Unit; Harris, I.C.; Jones, P.D. (2017): CRU TS4.00: Climatic Research Unit (CRU) Time-Series (TS) version 4.00 of high-resolution gridded data of month-by-month variation in climate (Jan. 1901- Dec. 2015). Centre for Environmental Data Analysis, 25 August 2017. doi:10.5285/edf8febfdaad48abb2cbaf7d7e846a86. http://dx.doi.org/10.5285/edf8febfdaad48abb2cbaf7d7e846a86
(see controlled vocabulary: Climatic Zone 2019)
mean_srtm_alt_90m_year1994 number mean value within a radius of 90 m around station location of the following data of the year 1994:
units: m
data_source: NASA Shuttle Radar Topographic Mission (SRTM)
citation: Jarvis, A., H.I. Reuter, A. Nelson, E. Guevara, 2008, Hole-filled SRTM for the globe Version 4, available from the CGIAR-CSI SRTM 90m Database (http://srtm.csi.cgiar.org)
mean_srtm_alt_1km_year1994 number mean value within a radius of 1 km around station location of the following data of the year 1994:
units: m
data_source: NASA Shuttle Radar Topographic Mission (SRTM)
citation: Jarvis, A., H.I. Reuter, A. Nelson, E. Guevara, 2008, Hole-filled SRTM for the globe Version 4, available from the CGIAR-CSI SRTM 90m Database (http://srtm.csi.cgiar.org)
max_srtm_relative_alt_5km_year1994 number maximum value within a radius of 5 km around station location with relative altitude of the following data of the year 1994:
units: m
data_source: NASA Shuttle Radar Topographic Mission (SRTM)
citation: Jarvis, A., H.I. Reuter, A. Nelson, E. Guevara, 2008, Hole-filled SRTM for the globe Version 4, available from the CGIAR-CSI SRTM 90m Database (http://srtm.csi.cgiar.org)
min_srtm_relative_alt_5km_year1994 number minimum value within a radius of 5 km around station location with relative altitude of the following data of the year 1994:
units: m
data_source: NASA Shuttle Radar Topographic Mission (SRTM)
citation: Jarvis, A., H.I. Reuter, A. Nelson, E. Guevara, 2008, Hole-filled SRTM for the globe Version 4, available from the CGIAR-CSI SRTM 90m Database (http://srtm.csi.cgiar.org)
htap_region_tier1_year2010 string value for the year 2010 of the following data: The 'tier1' region defined in the task force on hemispheric transport of air pollution (TFHTAP) coordinated model studies according to figure 4 of https://publications.jrc.ec.europa.eu/repository/bitstream/JRC102552/lbna28255enn.pdf (see controlled vocabulary: Station HTAP Region)
dominant_landcover_year2012 string value for the year 2012 of the following data:
units: -
data_source: ESA 2017 and UCLouvain
citation: ESA. Land Cover CCI Product User Guide Version 2. Tech. Rep. (2017). Available at: http://maps.elie.ucl.ac.be/CCI/viewer/download/ESACCI-LC-Ph2-PUGv2_2.0.pdf
(see controlled vocabulary: Station Landcover Type)
dominant_ecoregion_year2017 string value for the year 2017 of the following data:
units: -
data_source: RESOLVE Biodiversity and Wildlife Solutions
citation: Eric Dinerstein, David Olson, Anup Joshi, Carly Vynne, Neil D. Burgess, Eric Wikramanayake, Nathan Hahn, Suzanne Palminteri, Prashant Hedao, Reed Noss, Matt Hansen, Harvey Locke, Erle C Ellis, Benjamin Jones, Charles Victor Barber, Randy Hayes, Cyril Kormos, Vance Martin, Eileen Crist, Wes Sechrest, Lori Price, Jonathan E. M. Baillie, Don Weeden, Kieran Suckling, Crystal Davis, Nigel Sizer, Rebecca Moore, David Thau, Tanya Birch, Peter Potapov, Svetlana Turubanova, Alexandra Tyukavina, Nadia de Souza, Lilian Pintea, Jose C. Brito, Othman A. Llewellyn, Anthony G. Miller, Annette Patzelt, Shahina A. Ghazanfar, Jonathan Timberlake, Heinz Klöser, Yara Shennan-Farpon, Roeland Kindt, Jens-Peter Barnekow Lilleso, Paulo van Breugel, Lars Graudal, Maianna Voge, Khalaf F. Al-Shammari, Muhammad Saleem, An Ecoregion-Based Approach to Protecting Half the Terrestrial Realm, BioScience, Volume 67, Issue 6, June 2017, Pages 534–545, https://doi.org/10.1093/biosci/bix014
(see controlled vocabulary: Station ECO Region Type)
distance_to_major_road_year2020 number value for the year 2020 of the following data:
version: 0.6
generator: Overpass API 0.7.57.2 48842a1b
copyright: https://www.openstreetmap.org/copyright
timestamp: 2022-04-22T17:10:56Z
mean_nightlight_1km_year2013 number mean value within a radius of 1 km around station location of the following data of the year 2013:
units: -
data_source: NOAA National Centers for Environmental Information (NCEI)
citation: Image and data processing by NOAA's National Geophysical Data Center. DMSP data collected by US Air Force Weather Agency
mean_nightlight_5km_year2013 number mean value within a radius of 5 km around station location of the following data of the year 2013:
units: -
data_source: NOAA National Centers for Environmental Information (NCEI)
citation: Image and data processing by NOAA's National Geophysical Data Center. DMSP data collected by US Air Force Weather Agency
max_nightlight_25km_year2013 number maximum value within a radius of 5 km around station location of the following data of the year 2013:
units: -
data_source: NOAA National Centers for Environmental Information (NCEI)
citation: Image and data processing by NOAA's National Geophysical Data Center. DMSP data collected by US Air Force Weather Agency
max_nightlight_25km_year1992 number maximum value within a radius of 25 km around station location of the following data of the year 2013:
units: -
data_source: NOAA National Centers for Environmental Information (NCEI)
citation: Image and data processing by NOAA's National Geophysical Data Center. DMSP data collected by US Air Force Weather Agency
mean_population_density_250m_year2015 number mean value within a radius of 250 m around station location of the following data of the year 2015:
units: 1/km^2
data_source: The European Commission, Joint Research Centre
citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f
mean_population_density_5km_year2015 number mean value within a radius of 5 km around station location of the following data of the year 2015:
units: 1/km^2
data_source: The European Commission, Joint Research Centre
citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f
max_population_density_25km_year2015 number maximum value within a radius of 25 km around station location of the following data of the year 2015:
units: 1/km^2
data_source: The European Commission, Joint Research Centre
citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f
mean_population_density_250m_year1990 number mean value within a radius of 250 m around station location of the following data of the year 1990:
units: 1/km^2
data_source: The European Commission, Joint Research Centre
citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f
mean_population_density_5km_year1990 number mean value within a radius of 5 km around station location of the following data of the year 1990:
units: 1/km^2
data_source: The European Commission, Joint Research Centre
citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f
max_population_density_25km_year1990 number maximum value within a radius of 25 km around station location of the following data of the year 1990:
units: 1/km^2
data_source: The European Commission, Joint Research Centre
citation: Schiavina, Marcello; Freire, Sergio; MacManus, Kytt (2019): GHS-POP R2019A - GHS population grid multitemporal (1975-1990-2000-2015). European Commission, Joint Research Centre (JRC) [Dataset] doi:10.2905/0C6B9751-A71F-4062-830B-43C9F432370F PID: http://data.europa.eu/89h/0c6b9751-a71f-4062-830b-43c9f432370f
mean_nox_emissions_10km_year2015 number mean value within a radius of 10 km around station location of the following data of the year 2015:
units: kg m-2 s-1
data_source: https://atmosphere.copernicus.eu/sites/default/files/2019-06/cams_emissions_general_document_apr2019_v7.pdf
citation: Granier, C., S. Darras, H. Denier van der Gon, J. Doubalova, N. Elguindi, B. Galle, M. Gauss, M. Guevara, J.-P. Jalkanen, J. Kuenen, C. Liousse, B. Quack, D. Simpson, K. Sindelarova The Copernicus Atmosphere Monitoring Service global and regional emissions (April 2019 version) Report April 2019 version null 2019 Elguindi, Granier, Stavrakou, Darras et al. Analysis of recent anthropogenic surface emissions from bottom-up inventories and top-down estimates: are future emission scenarios valid for the recent past? Earth's Future null submitted 2020
mean_nox_emissions_10km_year1990 number mean value within a radius of 10 km around station location of the following data of the year 1990:
units: kg m-2 s-1
data_source: https://atmosphere.copernicus.eu/sites/default/files/2019-06/cams_emissions_general_document_apr2019_v7.pdf
citation: Granier, C., S. Darras, H. Denier van der Gon, J. Doubalova, N. Elguindi, B. Galle, M. Gauss, M. Guevara, J.-P. Jalkanen, J. Kuenen, C. Liousse, B. Quack, D. Simpson, K. Sindelarova The Copernicus Atmosphere Monitoring Service global and regional emissions (April 2019 version) Report April 2019 version null 2019 Elguindi, Granier, Stavrakou, Darras et al. Analysis of recent anthropogenic surface emissions from bottom-up inventories and top-down estimates: are future emission scenarios valid for the recent past? Earth's Future null submitted 2020

Response: Each query result 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.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=100000

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 geolocation 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.fz-juelich.de/api/v2/timeseries/[?QUERY-OPTIONS]

where QUERY-OPTIONS are:

Name Type Description
limit integer count (default: 10)
offset integer number of elements to be skipped (default: 0)
id integer internally (in the database) used id of the time series
label string a short string to distinguish this timeseries from others with the same combination of station and variable
order integer indicates position of this timeseries in a list when several timeseries share the same station and variable combination
sampling_frequency string Sampling frequency of data in this timeseries (see controlled vocabulary: Sampling Frequency)
aggregation string Aggregation type in this timeseries (see controlled vocabulary: Aggregation Type)
data_start_date dateTime Start date of the variable data available for this station
data_end_date dateTime End date of the variable data available for this station
data_origin string origin of data (model name or instrument) (see controlled vocabulary: Data Origin)
data_origin_type string type of data origin (see controlled vocabulary: Data Origin Type)
version string provider data version
sampling_height number Height above the ground of the inlet/instrument/sampler (in m)
station_id integer internal id of the station where the measurements take place
variable_id integer internal id of the variable which is related to this time series

Response: Each query result 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.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”:”2050-01-01T00:00:00+00:00”,”data_end_date”:”1900-01-01T00: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.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”:”2050-01-01T00:00:00+00:00”,”data_end_date”:”1900-01-01T00: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.

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=100000

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.fz-juelich.de/api/v2/data/timeseries/[id][?QUERY-OPTIONS]
or
https://toar-data.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 query result consists of the fields that are specified in the columns argument. If columns are not specified, the output of each record will consist of the fieldsseries_id, network_name, station_id, parameter_label as the series query.

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

Example: https://toar-data.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.fz-juelich.de/api/v2/data/timeseries/52?format=csv

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

2.9 Geolocation URLs

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

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

2.10 Database statistics

https://toar-data.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.fz-juelich.de/api/v2/database_statistics/

Result:

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

4. Python example

The following python code provides a recipe how data can be obtained from the TOAR database through the REST services described above. In this example, the received data is splitted into its metadata and data part.

"""
toar_rest_demo: demonstrate use the REST interface to TOAR database v2 from python

@author: s.schroeder, Forschungszentrum Juelich GmbH, Germany (s.schroeder@fz-juelich.de)
@date:   2022-02-07
"""
from io import StringIO
import json
import pandas as pd
import requests

TOAR_SERVICE_URL="https://toar-data.fz-juelich.de/api/v2/"

# get data from the REST service
flags = None
timeseries_id=21
if flags:
        result=requests.get(TOAR_SERVICE_URL+f'data/timeseries/{timeseries_id}?flags={flags}&format=csv')
else:
    result=requests.get(TOAR_SERVICE_URL+f'data/timeseries/{timeseries_id}?format=csv')
timeseries_meta = json.loads("\n".join([line[1:] for line in result.text.split('\n') if line.startswith('#')]))
df = pd.read_csv(StringIO(result.text), comment='#', header=1, sep=',',names=["time","value","flags","version","timeseries_id"],parse_dates=["time"],index_col="time",date_parser=lambda x:pd.to_datetime(x,utc=True),infer_datetime_format=True)

# print, what I got
print(f"metadata: {timeseries_meta}")
print(f"data: {df}")

# example of how to access metadata
stationmeta=timeseries_meta["station"]
variable=timeseries_meta["variable"]
data_start_date = min(df.index).strftime("%Y-%m-%d %H:%M:%S+00")
data_end_date = min(df.index).strftime("%Y-%m-%d %H:%M:%S+00")

# show stationmeta data
print(f'retrieved data from station {stationmeta["name"]} for variable {variable["name"]} with timerange {data_start_date} - {data_end_date}')
print(f'station coordinates: {stationmeta["coordinates"]}')