REST-API für den Abruf von KOSTRA-Daten

Neben den Tabellen im PDF-Format wird nun auch eine REST-API für den automatisierten Abruf von maschinenlesbaren KOSTRA-Daten angeboten.

Die API ist gegenwärtig auf dem Stand einer Beta-Version und derzeit eingeschränkt öffentlich zugänglich. Das heißt, dass im Moment für die Abfrage ein API-Key erforderlich ist, der interessierten Testern aber kostenlos zur Verfügung gestellt wird. Hierzu einfach eine kurze Mail mit der Anfrage nach einem Schlüssel an kontakt@openko.de senden.

Funktionsumfang der REST-API

Die API hat drei Endpunkte, über die KOSTRA-DWD-2020-Daten abgerufen werden können. Zum einen besteht die Möglichkeit, den vollständigen Datensatz eines Rasterfeldes über dessen Nummer abzurufen. Zum anderen können über die Angabe einer beliebigen Koordinate (mit EPSG-Code) entweder die Nummer des dort relevanten Rasterfeldes oder ebenfalls der vollständige Datensatz abgerufen werden. Die Endpunkte sind wie folgt erreichbar:

  • https://dva3.de/kostra-rest/get_values_by_index
  • https://dva3.de/kostra-rest/get_index_by_coordinate
  • https://dva3.de/kostra-rest/get_values_by_coordinate

Weiteres kann über eine Swagger UI unter https://dva3.de/docs eingesehen und auch interaktiv getestet werden.

Beispielaufrufe mit cURL

Der Datensatz zu gegebenen Rasterfeld (z.B. Nr. 149100) kann mit cURL wie folgt abgerufen werden:

curl -X 'GET' \
'https://dva3.de/kostra-rest/get_values_by_index/?index=149100' \
-H 'accept: application/json' \
-H 'api-key: valid-api-key-here'

Der Rückgabewert ist ein JSON-String, der als Schlüssel die Dauerstufe in Minuten verwendet. Hinter jeder Dauerstufe werden sämtliche Werte für Bemessungsniederschlagswerte, Regenspende und örtliche Unsicherheit angegeben. Beispielhafter Auszug einer solchen Rückgabe:

{
„5“: {
„HN_001A“: 5.1,
„HN_002A“: 6.2,
…
„RN_001A“: 170,
„RN_002A“: 206.7,
…
„UC_001A“: 16,
„UC_002A“: 15,
…
„UC_100A“: 14
},
„10“: {
„HN_001A“: 7.5,
…

Soll eine Rasterfeldnummer über eine Koordinate gefunden werden, ist der Abruf beispielsweise wie folgt aufgebaut:

curl -X 'GET' \
'https://dva3.de/kostra-rest/get_index_by_coordinate/?x=364422.33&y=5707281.52&epsg=25832' \
-H 'accept: application/json' \
-H 'api-key: valid-api-key-here'

Der Rückgabewert ist die Nummer des hier relevanten Rasterfeldes als Integer.

Soll der Datensatz über eine Koordinate abgerufen werden, ist die cURL-Abfrage beispielsweise wie folgt aufgebaut:

curl -X 'GET' \
'https://dva3.de/kostra-rest/get_values_by_coordinate/?x=364422.33&y=5707281.52&epsg=25832' \
-H 'accept: application/json' \
-H 'api-key: valid-api-key-here'

Beispiel mit Python-Skript

Die API kann auch beispielsweise in Python-Skripten verwendet werden, die die abgerufenen Daten noch weiter verarbeiten können. Hier kann der Abruf mit dem Python-Modul requests erfolgen.

Nachfolgend wird beispielhaft ein kleines Skript gezeigt, dass die REST-API-Anfrage in eine Funktion mit einigen Fehlerbehandlungen einbaut. Es wird ein vollständiger KOSTRA-DWD-2020-Datensatz auf Basis einer Koordinate abgefragt und anschließend Niederschlagshöhe und Regenspende für ein 5-minütiges Niederschlagsereignis bei einer 100-jährigen Wiederkehrzeit anzeigt:

Anzeige