PEGELONLINE REST-API User's Guide

Über die PEGELONLINE REST-API können die gewässerkundlichen Daten von PEGELONLINE auf einfache Weise abgefragt werden, um sie z.B. auf einer externen Webseite oder in einer mobilen App zu nutzen.

Die Daten sind über HTTP-URLs adressierbar. Das Ergebnis wird in JSON-Notation erzeugt.

Die API wird in ihrer Dokumentation detaillierter beschrieben.

Beispielabfragen

Eine Abfrage aller verfügbaren Messstellen von PEGELONLINE erfolgt mit dieser URL:

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations.json

Die Messstellen enthalten weitere untergeordnete Informationen zu den Zeitreihen und zum gerade aktuell gemessenen Wert. Diese Daten können folgendermaßen angefordert werden:

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations.json?includeTimeseries=true&includeCurrentMeasurement=true

Die Messstellen enthalten jetzt jeweils das Element timeseries, in dem eine odere mehrere Zeitreihen beschrieben sind, welche an der Messstelle verfügbar sind. Jede Timeseries enthält das Element currentMeasurement, in dem der aktuell gemessene Wert enthalten ist.

Die Liste der Messstellen kann z.B. auf bestimmte Gewässer beschränkt werden.

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations.json?waters=RHEIN,MAIN

Der aktuelle gemessene Wasserstand einer einzelnen Messstelle kann entweder zusammen mit den Messstelleninformationen..

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868.json?includeTimeseries=true&includeCurrentMeasurement=true

oder auch isoliert abgefragt werden.

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/currentmeasurement.json

Die Messstellen werden dabei mit ihrer UUID identifiziert. Die UUIDs sind in der Pegeltabelle aufgelistet oder können aus https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations.json entnommen werden.

Zusätzliche Informationen zu den verfügbaren Vorhersagezeitreihen können folgendermaßen abgefragt werden:

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations.json?includeTimeseries=true&hasTimeseries=WV&includeForecastTimeseries=true

Die Zeitreihen heißen hier "Wasserstandvorhersage" (WV).

Die gemessenen Rohwerte einer Zeitreihe an einer Messstelle können über die Ressource Measurement im JSON-Format abgefragt werden. Folgende URL ruft die Messwerte der letzten 15 Tage ab ('P15D' ist eine ISO_8601 Zeitspanne.). Alternativ kann für den Parameter start auch ein ISO_8601 Zeitpunkt angegeben werden.

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.json?start=P15D

Alternativ kann der Abruf auch im CSV-Format erfolgen. Dazu ändert man die Endung zu csv.

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.csv?start=P15D

Die Messwerte können auch als PNG-Image visualisiert werden. Dazu ändert man die Endung zu png.

https://pegelonline-prod.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.png?start=P15D

Das Format, in dem der Server die Daten ausliefert, wird also über die Endung in der URL bestimmt.

Einbettung der Ganglinienvisualisierung in externe Webseiten über HTML

Folgendes Beispiel zeigt die Einbettung einer Ganglinienvisualisierung mit Wasserstandsdaten der letzten 15 Tage in eine externe Webseite. Die Darstellung wird durch einen regulären HTML Img-Tag angefordert.

<img
    src="https://pegelonline-int.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868/W/measurements.png?start=P15D&width=925&height=220"
    width="925"
    height="220"/>

Ergebnis:

Einbettung der Daten in externe Webseiten über Javascript

Folgendes Beispiel zeigt die Einbettung der Daten in eine externe Webseite mit Hilfe von JavaScript und jQuery. Es werden Daten über der Messstelle Bonn über ihre UUID angefordert und diese innerhalb eines HTML-Elements dargestellt.

$.getJSON('https://pegelonline-int.wsv.de/webservices/rest-api/v2/stations/593647aa-9fea-43ec-a7d6-6476a76ae868.json',
    function(station) {
        var html =
            '<ul>' +
                '<li>Name: ' + station.longname + '</li>' +
                '<li>Nummer: ' + station.number + '</li>' +
                '<li>UUID: ' + station.uuid + '</li>' +
                '<li>Gewässer: ' + station.water.longname + '</li>' +
            '</ul>';
 
        $('#ergebnisfenster').html(html);
    });

Weitere Hinweise

Caching

Die API unterstützt clientseitiges Caching durch die HTTP Header Cache-Control, Expires und Etag.

Durch die Verwendung von Expires und max-age im HTTP Header Cache-Control, kann für eine gewisse Zeit ein HTTP-Request gänzlich entfallen. Durch den Header Etag sendet der Server nur dann die angeforderten Daten zurück, wenn sie sich auf der Serverseite verändert haben.

Weiterführende Hinweise gibt es in im entsprechenden Abschnitt der Dokumentation.

UUID

Auf die Messstellen sollte sich nur per UUID bezogen werden. Messstellennummer oder -namen können sich verändern bzw. sind nicht eindeutig.

Kompression

Siehe entsprechenden Abschnitt in der Dokumentation.

Umgang mit Sonderzeichen in URLs

Siehe entsprechenden Abschnitt in der Dokumentation.

Haftung und Lizenz

Die Wasserstraßen- und Schifffahrtsverwaltung des Bundes (WSV) stellt ungeprüfte Rohdaten bereit. Daher wird keine Haftung oder Gewährleistung für die inhaltliche Richtigkeit, Genauigkeit, Aktualität, Zuverlässigkeit oder Vollständigkeit der Daten übernommen.
Die Daten sind unter der Lizenz DL-DE->Zero-2.0 frei verfügbar.