API Documentation

Authentication guide

This website/data interface is intended to be used by students taking courses at the Digital Science Center at the Universität Innsbruck and not for public access to this data set. The data set is publicly available via the GeoSphere Austria Data Hub.
Thus, data requests require a valid APICODE; the station search does not require such a code. In case you are requesting data the API will respond with the desired format (e.g., XML/JSON), however, the output will only contain an error message (invalid code) and no data!.
Students/participants of our courses will get a valid APICODE as soon as needed.

Endpoint definitions

Two different end-points are available:

To retrieve station information (including station search)
To retrieve data (observation data)

Information about how to use the API end-points is not only provided here, but also often on the corresponding pages (e.g., see here). Example requests are also shown below beside the description of the return format.

Station search end-point

Basic

https://meteoapi.discdown.org/api/station-search
Basic call, returns all available stations; XML.

Search phrase (str)

https://meteoapi.discdown.org/api/station-search?searchPhrase=Berlin
The optiona GET-argument searchPhrase (str) allows to filter the stations by string (string matching). searchPhrase=Berlin will filter the station list and only include stations which either contain Berlin in their name, or in the 'land' (location). Special case: if searchPhrase represents an integer; see below.

Search phrase (int)

https://meteoapi.discdown.org/api/station-search?searchPhrase=1
In case the optional GET-argument represents an integer (e.g., 1 or 00001; matching ^[0-9]+$) the API will filter for the station with this specific ID.

Data request end-point

Usage

https://meteoapi.discdown.org/api/data/APICODE/format/station_ID/[year][?limit=integer] Basic call, returns all available stations; XML. The different parameters in the URI/URL are described next.

APICODE

A valid API code is required to request data via the API, see Authentication guide for details.

format

Required, format must be one of xml or json. For examples, see examples section.

year

If not specified, the API will return all available data. Can be specified (e.g., /2020) to only get data from the year 2020 (if available).

limit

Additional GET argument, mainly used for testing/development. If set, the API will return the first N observations only (if N or more than N observations are available).

Errors: In case the station does not exist (station_ID is not a valid station identifier) the API will respond with a "404 not found" request. The same yields for invalid format.

If a station is valid but does not provide any data, the API responds with a message in the desired format (XML/JSON) containing an error message that no data is available. Either because the station did not record any data for a specific year (if set) or not at all. Some stations did not record any climatological data in their entire live-time.

As for 'no data', the API will respond in the desired format (XML/JSON) if your APICODE is invalid. The response contains an error message that your API request code was invalid. For your participants: just ask your lecturer(s) for a valid code, if needed.

Station information example response

URL

https://meteoapi.discdown.org/api/station-search?format=xml&searchPhrase=32

Note

Returns station information for one specific station, here 32 as searchPhrase=32. The optional argument searchPhrase can also contain a character string to filter stations. searchPhrase=Berlin will return all stations which either contain Berlin in their station name, or in the name of 'land'. Not case sensitive.

Description

Returns an XML 1.0 document; the root node stations. The root node can contain 0 or more stations depending on the searchPhrase used.

station: Each station node comes with three attributes, namely the id (five-digit station ID, integer with leading zeros), begin and end. The latter two define the time period where observations for this specific station should be available. As this server only mirrors historical data on irregular intervals, the end-date might not match the latest observations in the data sets. Moreover, each station node contains information about the name of the station and its location. See station details for more information).



<?xml version='1.0' encoding='utf-8'?>
<stations description="MeteoAPI">
  <station id="00032" data_from="1949-01-01" data_to="2024-06-20">
    <name>GUMPOLDSKIRCHEN</name>
    <state>Niederösterreich</state>
    <longitude unit="degrees east">16.280834</longitude>
    <latitude unit="degrees north">48.035831</latitude>
    <altitude unit="m a.m.s.l.">212</altitude>
    <parameters>
      <parameter name="druckmit" long_name="Luftdruck Tagesmittel" unit="hPa">Luftdruck, Tagesmittel der Beobachtungstermine - (druck07 + druck14 + druck19) / 3</parameter>
      <parameter name="erdmin" long_name="5 cm Lufttemperatur Minimum" unit="°C">Lufttemperatur +5cm Nachtminimum zum Beobachtungstermin I (19 Uhr MEZ Vortag bis 7 Uhr MEZ)</parameter>
      <parameter name="neuschnee" long_name="Neuschneehöhe zum Beobachtungstermin I" unit="cm">Neuschneehöhe, Tageswert um 7 Uhr MEZ bzw. MOZ - Gemessen um 07:00 Uhr MEZ bzw. MOZ,  (-1 = kein Schnee, 0 = unter 1 cm)</parameter>
      <parameter name="nied" long_name="Niederschlagssumme" unit="mm">für reine Beobachtungsstationen: 24-stündiger Handniederschlag (KSE):  7 MEZ aktueller Tag - 7 MEZ folgender Tag, sonst Summe der 12-stündigen Handniederschläge nied19 und nied07 / für reine Automatenstationen und Stationen mit Beobachtung und Automat: Summe der Minutenwerte von RR: 07:01 MEZ  - 07:00 MEZ Folgetag / Spuren aus RRM berechnet, wenn vorhanden; -1 = kein Niederschlag, 0 = Spuren, weniger als 1/10 mm - nied19 (akt. Tag) + nied07 (Folgetag)</parameter>
      <parameter name="nieda" long_name="Niederschlagsart 7:01 MEZ - 7:00 MEZ Folgetag" unit="Code">Niederschlagsart, 24stündig - Beobachtung (KSE), sofern vorhanden: direkt beobachtet 24-stündig oder aus zwei Terminen berechnet: aus nied19a desselben und nied07a des Folgetages - nied19a (aktueller Tag) + nied07a (Folgetag), Tabelle klima.tag_code_niederschlagsart - klima.tag_code_niederschlagsart={0: kein Niederschlag, 1: Regen, 2: Schnee, 3: Graupel, 4: Hagel, 5: Regen und Schnee, 6: Regen und Graupel, 7: Regen und Hagel, 8: Schnee und Graupel, 9: Graupel und Hagel, 10: Regen und Schnee und Graupel, 11: Regen und Graupel und Hagel, 12: Schnee und Hagel, 13: Regen und Schnee und Hagel, 14: Schnee und Graupel und Hagel, 15: Regen und Schnee und Graupel und Hagel, 99: nicht gemessen}</parameter>
      <parameter name="rel" long_name="Relative Feuchte Tagesmittel" unit="%">Relative Feuchte Tagesmittel - (rel07 + rel14 + rel19) / 3</parameter>
      <parameter name="schnee" long_name="Gesamtschneehöhe zum Beobachtungstermin I" unit="cm">Gesamtschneehöhe um 7 Uhr MEZ bzw. MOZ - Gemessen um 07:00 Uhr MEZ bzw. MOZ,  (-1 = kein Schnee, 0 = unter 1 cm)</parameter>
      <parameter name="sonne" long_name="Sonnenscheindauer 24h-Summe" unit="h">Sonnenscheindauer 24h-Summe aus Stundenwerten</parameter>
      <parameter name="t" long_name="Lufttemperaturmittel 2m" unit="°C">Lufttemperatur in 2m Höhe, Tagesmittel aus Extremwerten gerechnet - (tmax + tmin) / 2</parameter>
      <parameter name="tmax" long_name="Lufttemperatur 2m Maximum" unit="°C">Lufttemperatur in 2m Höhe, Tagesmaximum (19 Uhr MEZ Vortag bis 19 Uhr MEZ)</parameter>
      <parameter name="tmin" long_name="Lufttemperatur 2m Minimum" unit="°C">Lufttemperatur in 2m Höhe, Tagesminimum (19 Uhr MEZ Vortag bis 19 Uhr MEZ)</parameter>
      <parameter name="vv" long_name="Windgeschwindigkeit Tagesmittel" unit="m/s">Windgeschwindigkeit, Tagesmittel aus den Terminwerten - (vv07 + vv14 + vv19) / 3, wobei jeder Beaufort-Wert erst in 1/10 m/s umgerechnet wird</parameter>
    </parameters>
  </station>
</stations>

Data example response

An optional argument parameters can be provided to only retrieve observations for a specific parameter (e.g., only minimum temperature or only minimum and maximum temperature). This can be controlled via ?parameters as described below. If not set, all available data will be returned.

XML

URL

https://meteoapi.discdown.org/api/data/APICODE/xml/32/2024?limit=3

APICODE

See Authentication guide

Note

Returns the data in the XML format for station 32, only the first 3 observations available in year 2024.

Description

Returns an XML 1.0 document; the root node meteoapi contains three nodes:

source: Information from which api the data set has been loaded, when the file has been generated, and what the original_source of the data set is.

station: Besides the attribute with the station id (five digit integer, leading zeros) the node contains the information of the station the observations belong to. See station details for more information).

observations: Contains the actual observations; JSON array. The attributes of the node declare the format (format="json") and the number of observations (number_of_observations). All arrays in the JSON object are of the same length. The API only returns parameters available for this specific site. Missing values coded as -999 (information included in XML/JSON file).



<?xml version='1.0' encoding='UTF-8'?>
<meteoapi api="MeteoAPI">
  <missing_values>-999</missing_values>
  <source>
    <api>DiSC/DiSCdown MeteoAPI</api>
    <datetime>2024-06-24 13:49:38</datetime>
    <original_source>GeoSphere Austria</original_source>
  </source>
  <station id="00032">
    <name>GUMPOLDSKIRCHEN</name>
    <state>Niederösterreich</state>
    <longitude>16.280834</longitude>
    <latitude>48.035831</latitude>
    <altitude>212</altitude>
  </station>
  <parameters>
    <parameter name="druckmit">Luftdruck, Tagesmittel der Beobachtungstermine - (druck07 + druck14 + druck19) / 3</parameter>
    <parameter name="erdmin">Lufttemperatur +5cm Nachtminimum zum Beobachtungstermin I (19 Uhr MEZ Vortag bis 7 Uhr MEZ)</parameter>
    <parameter name="neuschnee">Neuschneehöhe, Tageswert um 7 Uhr MEZ bzw. MOZ - Gemessen um 07:00 Uhr MEZ bzw. MOZ,  (-1 = kein Schnee, 0 = unter 1 cm)</parameter>
    <parameter name="nied">für reine Beobachtungsstationen: 24-stündiger Handniederschlag (KSE):  7 MEZ aktueller Tag - 7 MEZ folgender Tag, sonst Summe der 12-stündigen Handniederschläge nied19 und nied07 / für reine Automatenstationen und Stationen mit Beobachtung und Automat: Summe der Minutenwerte von RR: 07:01 MEZ  - 07:00 MEZ Folgetag / Spuren aus RRM berechnet, wenn vorhanden; -1 = kein Niederschlag, 0 = Spuren, weniger als 1/10 mm - nied19 (akt. Tag) + nied07 (Folgetag)</parameter>
    <parameter name="nieda">Niederschlagsart, 24stündig - Beobachtung (KSE), sofern vorhanden: direkt beobachtet 24-stündig oder aus zwei Terminen berechnet: aus nied19a desselben und nied07a des Folgetages - nied19a (aktueller Tag) + nied07a (Folgetag), Tabelle klima.tag_code_niederschlagsart - klima.tag_code_niederschlagsart={0: kein Niederschlag, 1: Regen, 2: Schnee, 3: Graupel, 4: Hagel, 5: Regen und Schnee, 6: Regen und Graupel, 7: Regen und Hagel, 8: Schnee und Graupel, 9: Graupel und Hagel, 10: Regen und Schnee und Graupel, 11: Regen und Graupel und Hagel, 12: Schnee und Hagel, 13: Regen und Schnee und Hagel, 14: Schnee und Graupel und Hagel, 15: Regen und Schnee und Graupel und Hagel, 99: nicht gemessen}</parameter>
    <parameter name="rel">Relative Feuchte Tagesmittel - (rel07 + rel14 + rel19) / 3</parameter>
    <parameter name="schnee">Gesamtschneehöhe um 7 Uhr MEZ bzw. MOZ - Gemessen um 07:00 Uhr MEZ bzw. MOZ,  (-1 = kein Schnee, 0 = unter 1 cm)</parameter>
    <parameter name="sonne">Sonnenscheindauer 24h-Summe aus Stundenwerten</parameter>
    <parameter name="t">Lufttemperatur in 2m Höhe, Tagesmittel aus Extremwerten gerechnet - (tmax + tmin) / 2</parameter>
    <parameter name="tmax">Lufttemperatur in 2m Höhe, Tagesmaximum (19 Uhr MEZ Vortag bis 19 Uhr MEZ)</parameter>
    <parameter name="tmin">Lufttemperatur in 2m Höhe, Tagesminimum (19 Uhr MEZ Vortag bis 19 Uhr MEZ)</parameter>
    <parameter name="vv">Windgeschwindigkeit, Tagesmittel aus den Terminwerten - (vv07 + vv14 + vv19) / 3, wobei jeder Beaufort-Wert erst in 1/10 m/s umgerechnet wird</parameter>
  </parameters>
  <observations format="json" number_of_obs="3">{"datum": ["2024-06-18", "2024-06-19", "2024-06-20"], "druckmit": [990.9, 988.2, 995.6], "erdmin": [15.4, 14.4, 17.2], "nied": [-1.0, -1.0, -999.0], "rel": [53.0, 62.0, 63.0], "sonne": [12.9, 12.7, 6.2], "t": [24.1, 24.7, 23.9], "tmax": [30.2, 31.7, 28.8], "tmin": [17.9, 17.7, 19.0], "vv": [3.3, 2.1, 2.7], "nieda": [-999.0, -999.0, -999.0], "neuschnee": [-999.0, -999.0, -999.0], "schnee": [-999.0, -999.0, -999.0]}</observations>
</meteoapi>

JSON

URL

https://meteoapi.discdown.org/api/data/APICODE/json/32/2024?limit=3

APICODE

See Authentication guide

Note

Returns the data in the XML format for station 32, only the first 3 observations available in year 2024.

Description

Returns a JSON string with several objects.

source: Information from which api the data set has been loaded, when the file has been generated, and what the original_source of the data set is.

station (object): Contains information about the station to which the observations belong to. See station details for more information). Station id included as five-digit integer with leading zeros.

observations: Contains the actual observations; JSON array. The attributes of the node declare the format (format="json") and the number of observations (number_of_observations). All arrays in the JSON object are of the same length. The API only returns parameters available for this specific site. Missing values coded as -999 (information included in XML/JSON file).



Whoops, something went wrong generating the API demo output ...

XML: Specify parameters

An additional argument parameters=... can be provided where ... is a colon separated list of parameters (e.g., parameters=tmin:tmax:schnee:reto). The API will return data for these parameters if available. If not, the parameters will be dropped which may result in an empty return (no data available for the request).

URL

https://meteoapi.discdown.org/api/data/APICODE/xml/32/2024?parameters=tmin:tmax:schnee:reto&limit=3

APICODE

See Authentication guide

Note

Returns the data in the XML format for station 32, only the first 3 observations available in year 2024.

Description



<?xml version='1.0' encoding='UTF-8'?>
<meteoapi api="MeteoAPI">
  <missing_values>-999</missing_values>
  <source>
    <api>DiSC/DiSCdown MeteoAPI</api>
    <datetime>2024-06-24 13:49:39</datetime>
    <original_source>GeoSphere Austria</original_source>
  </source>
  <station id="00032">
    <name>GUMPOLDSKIRCHEN</name>
    <state>Niederösterreich</state>
    <longitude>16.280834</longitude>
    <latitude>48.035831</latitude>
    <altitude>212</altitude>
  </station>
  <parameters>
    <parameter name="schnee">Gesamtschneehöhe um 7 Uhr MEZ bzw. MOZ - Gemessen um 07:00 Uhr MEZ bzw. MOZ,  (-1 = kein Schnee, 0 = unter 1 cm)</parameter>
    <parameter name="tmax">Lufttemperatur in 2m Höhe, Tagesmaximum (19 Uhr MEZ Vortag bis 19 Uhr MEZ)</parameter>
    <parameter name="tmin">Lufttemperatur in 2m Höhe, Tagesminimum (19 Uhr MEZ Vortag bis 19 Uhr MEZ)</parameter>
  </parameters>
  <observations format="json" number_of_obs="3">{"datum": ["2024-06-18", "2024-06-19", "2024-06-20"], "tmin": [17.9, 17.7, 19.0], "tmax": [30.2, 31.7, 28.8], "schnee": [-999.0, -999.0, -999.0]}</observations>
</meteoapi>