EDIS Dict-API – Dokumentation
Die Dict-API ist ein zentraler Baustein, um die Nutzung der PEGELONLINE-Echtzeitdateninfrastruktur (EDIS) zu unterstützen. Ziel von EDIS ist eine möglichst schnelle und effiziente Auslieferung von Messdaten (weitere Informationen siehe: EDIS). Hierzu werden entsprechende Messdatenströme über einen MQTT-Broker angeboten.
Da das MQTT-Protokoll jedoch nur sehr eingeschränkte Möglichkeiten zur Recherche nach Datenströmen, die durch einen MQTT-Broker angeboten werden, bietet, wird diese Lücke durch die Dict-API geschlossen. Anhand verschiedener Suchparameter wie z.B. Stationsnamen, Bundesland, Gewässer, Parameter können PEGELONLINE-Stationen und Datenströme gefunden werden. Die Antwort auf eine Suchanfrage enthält neben grundlegenden Metadaten zu Stationen und Zeitreihen auch die Information, über welche Topics des EDIS-MQTT-Broker die jeweiligen Echtzeitdaten der Zeitreihen abonniert werden können.
Ebenso werden Links zum PEGELONLINE-REST-Service (REST-API) angeboten, welche es ermöglichen zu den jeweiligen Zeitreihen Messdaten aus der Vergangenheit abzurufen. Dies kann beispielsweise genutzt werden, um die über den MQTT-Broker ausgelieferten Echtzeit-Messwerte mit historischen Messdaten oder Referenzwerten in einen Kontext zu setzen.
Die Dict-API ist eine einfache API, welche das REST-Paradigma umsetzt. Sie ist über folgende URL erreichbar: Dict-API
Es ist keine Authentifizierung oder Autorisierung erforderlich, um die Dict-API zu nutzen.
Suche nach Stationen und ihren Zeitreihen
Um die Suche nach Stationen und ihren Zeitreihen auszuführen kann der /search Endpunkt der Dict-API verwendet werden. Zur Suche können folgende Suchparameter genutzt werden:
| Parameter | Beispiel | Beschreibung |
|---|---|---|
| station | station=köln | Stationen mit dem angegebenen Namen |
| gewaesser | gewaesser=rhein | Stationen an dem angegebenen Gewässer |
| agency | agency=dresden | Stationen mit der angegebenen Agency |
| land | land=hamburg | Stationen im angegebenen Bundesland |
| country | country=deutschland | Stationen im angegebenen Nationalstaat |
| einzugsgebiet | einzugsgebiet=ems | Stationen im angegebenen Einzugsgebiet |
| kreis | kreis=emsland | Stationen im angegebenen Landkreis |
| parameter | parameter=wassertemperatur | Stationen mit angegebenem Messparameter |
| bbox | bbox=7,52,8,53 | Stationen in der durch Koordinaten angegebenen Bounding Box (`minLon, minLat, maxLon, maxLat`) |
Bei Angabe mehrerer Parameter werden diese durch eine UND-Verknüpfung kombiniert. Beispiel:
Die Suche erfolgt via „String matching“, es wird nach exakten Matches gesucht innerhalb des Datenbestandes gesucht.
Zusätzlich gibt es einen Wildcard-Parameter, welcher über alle Stationsparameter sucht. Dieser ist nicht mit den regulären Suchparametern kombinierbar:
| Parameter | Beispiel | Beschreibung |
|---|---|---|
| q | q=köln | Allgemeiner Suchparameter, durch den alle Parameter durchsucht werden. Kann nicht mit anderen Parametern kombiniert werden. |
Ausgabe von Stationen und ihren Zeitreihen
Die Antwort auf eine Suchanfrage enthält ein JSON-Dokument mit folgenden Inhalten:
| Attribut | Beschreibung |
|---|---|
| mqtttopics | Liste aller Topics des MQTT-Broker, die zur Suchanfrage passen. |
| pegelonlinelinks | Liste der Links zum Download der verfügbaren Messdaten aller zur Suchanfrage passenden Zeitreihen (über die PEGELONLINE-REST-API). |
| stations | Liste aller Stationen mit ihren Zeitreihen, die zur Suchanfrage passen |
Die in der Antwort enthaltenen stations-Objekte enthalten folgende Informationen (dies ist eine Erweiterung der Ausgaben der PEGELONLINE-REST-API):
| Attribut | Beschreibung |
|---|---|
| uuid | Eindeutige unveränderliche ID. |
| number | Pegelnummer |
| shortname | Pegelname (max. 40 Zeichen) |
| longname | Pegelname (max. 255 Zeichen) |
| km | Flusskilometer |
| agency | Wasserstraßen- und Schifffahrtsamt |
| longitude | Längengrad in WGS84 Dezimalnotation |
| latitude | Breitengrad in WGS84 Dezimalnotation |
| water | Angaben zum Gewässer (shortname und longname) |
| timeseries | Die an der Station verfügbaren Zeitreihen (siehe unten) |
| country | Das Land, in dem sie die Station befindet |
| country_alternatives | Alternative Bezeichnungen für das Land, in dem sich die Station befindet |
| land | Das Bundesland, in dem sie die Station befindet |
| land_alternatives | Alternative Bezeichnungen für das Bundesland, in dem sich die Station befindet |
| kreis | Der Landkreis, in dem sie die Station befindet |
| kreis_alternatives | Alternative Bezeichnungen für den Landkreis, in dem sich die Station befindet |
| water_alternatives | Alternative Bezeichnungen für das Gewässer, an dem sich die Station befindet |
| Einzugsgebiet | Das Einzugsgebiet, in dem sich die Station befindet |
| mqtttopic | Das MQTT-Topic, über das Messdaten der Station abonniert werden können |
Die in der Antwort enthaltenen timeseries-Objekte enthalten folgende Informationen (dies ist eine Erweiterung der Ausgaben der PEGELONLINE-REST-API):
| Attribut | Beschreibung |
|---|---|
| shortname | Kurzbezeichnung |
| longname | Langbezeichnung |
| unit | Maßeinheit |
| equidistance | Abstand der Messwerte in Minuten |
| mqtttopic | Das MQTT-Topic, über das Messdaten der Zeitreihe abonniert werden können |
| pegelonlinelink | Link zum Download der Messdaten der Zeitreihe über die PEGELONLINE REST-API |
Das nachfolgende Beispiel zeigt exemplarische einen Auszug aus einer typischen Antwort der Dict-API auf eine Suchanfrage (hier mit dem Suchparameter „station=Münster“):
{
"mqtttopics": [
"edis/pegelonline/+/+/+/+/ccd3e8f1-39e9-4e09-aa41-625afda84460/+",
"edis/pegelonline/+/+/+/+/ed260406-bdd6-42ef-bf2a-1246eea392f9/+",
"edis/pegelonline/+/+/+/+/ccd3e8f1-39e9-4e09-aa41-625afda84460/+",
"edis/pegelonline/+/+/+/+/ed260406-bdd6-42ef-bf2a-1246eea392f9/+"
],
"pegelonlinelinks": [
"https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/ccd3e8f1-39e9-4e09-aa41-625afda84460/W/measurements.json",
"https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/ed260406-bdd6-42ef-bf2a-1246eea392f9/W/measurements.json",
"https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/ccd3e8f1-39e9-4e09-aa41-625afda84460/W/measurements.json",
"https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/ed260406-bdd6-42ef-bf2a-1246eea392f9/W/measurements.json"
],
"stations": [
{
"uuid": "ccd3e8f1-39e9-4e09-aa41-625afda84460",
"number": "27800040",
"shortname": "MÜNSTER OW",
"longname": "MÜNSTER OW",
"km": 70.315,
"agency": "RHEINE",
"longitude": 7.664374042081728,
"latitude": 51.968941959729285,
"water": {
"shortname": "DEK",
"longname": "DORTMUND-EMS-KANAL"
},
"timeseries": [
{
"shortname": "W",
"longname": "WASSERSTAND ROHDATEN",
"unit": "m+NN",
"equidistance": 1,
"mqtttopic": "edis/pegelonline/+/+/+/+/ccd3e8f1-39e9-4e09-aa41-625afda84460/W",
"pegelonlinelink": "https://www.pegelonline.wsv.de/webservices/rest-api/v2/stations/ccd3e8f1-39e9-4e09-aa41-625afda84460/W/measurements.json"
}
],
"country": "Deutschland",
"country_alternatives": [
"Germany",
"Niemcy",
"Alemaña",
"Allemagne",
"Duitsland"
],
"land": "Nordrhein-Westfalen",
"land_alternatives": [
"North Rhine-Westphalia",
"Nadrenia Północna-Westfalia",
"Rhénanie-du-Nord-Westphalie",
"Noordrijn-Westfalen"
],
"kreis": "Münster",
"kreis_alternatives": [
"Munster"
],
"water_alternatives": [
"DEK"
],
"einzugsgebiet": "Ems",
"mqtttopic": "edis/pegelonline/+/+/+/+/ccd3e8f1-39e9-4e09-aa41-625afda84460/+"
},
{
// Weitere Stationen
}
]
}
Testen der Dict-API via Swagger UI
Unter der URL Dict-API /search steht über Swagger UI eine Möglichkeit bereit, die Funktionalität der Dict-API über ein Web-Formular auszuprobieren. Hierzu werden für alle unterstützten Suchparameter entsprechende Eingabefelder angeboten, über die Nutzende ihre Suchparameter eingeben können (zum Aktivieren der Eingabefelder bitte auf den Button „Try it out“ klicken). Nach der Eingabe der Parameterwerte für die Suche, kann über die „Execute“-Schaltfläche eine Anfrage an die Dict-API gestellt werden:
Unterhalb der Eingabemaske wird das Ergebnis der Suchanfrage in einem separaten Feld dargestellt. Neben der eigentlichen Antwort der Dict-API erfolgt weiterhin eine Information darüber, über welchen HTTP-Aufruf die Anfrage an die Dict-API erfolgt ist und welche Inhalte der Header der Server-Antwort aufweist.
