WSV
PEGELONLINE PEGELONLINE Webservices PEGELONLINE

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. Der Server codiert das Ergebnis in JSON (JavaScript Object Notation).

Die API wird in ihrer Dokumentation detaillierter beschrieben.

Beispielabfragen

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

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

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.

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

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

Die gemessenen Rohwerte einer Zeitreihe an einer Messstelle können über die Ressource Measurement 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.

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

Das Format, in dem der Server die Daten ausliefert, wird also über die Endung bestimmt. Zukünftig werden weitere Formate wie z.B. XLS (Excel), XML oder GeoJSON angeboten.

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. 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.
1
2
3
4
5
6
7
8
9
10
11
12
    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.