PEGELONLINE HyDAS-API

Die PEGELONLINE HyDAS-API ist die Umsetzung des HydroDaten-API-Standards ↗ auf PEGELONLINE. Sie stellt Messstellen, deren Parameter und die zugehörigen Messwerte (Rohdaten) über eine schlanke, ressourcenorientierte HTTP-Schnittstelle im JSON-Format bereit.

Schnelleinstieg

Alle Ressourcen sind unterhalb der Basis-URL https://www.pegelstaende.de/api/v1 erreichbar. Die folgenden Beispiele lassen sich direkt anklicken und liefern echte Daten zurück.

1. Messstellen (stations) auflisten. Diese Abfrage liefert alle verfügbaren Messstellen:

2. Einzelne Messstelle gezielt abrufen. Über den Parameter ids lässt sich die Liste auf eine oder mehrere Messstellen-UUIDs einschränken (kommagetrennt). Die UUIDs sind in der Pegeltabelle aufgelistet oder können aus https://www.pegelstaende.de/api/v1/stations entnommen werden.

Beispiel für die Messstelle Bonn am Rhein:

Messstellen werden ausschließlich über ihre unveränderliche id (UUID) identifiziert.

3. Parameter einer Messstelle ermitteln. Jede Messstelle stellt einen oder mehrere Parameter bereit (z. B. Wasserstand oder Abfluss). Die id eines Parameters wird im nächsten Schritt benötigt:

Der Wasserstand auf PEGELONLINE trägt z. B. die Parameter-Id W, der Abfluss Q.

4. Messwerte (Zeitreihe) abrufen. Mit Messstelle-Id und Parameter-Id lassen sich die Messwerte abfragen. Der Zeitraum wird optional über from und to im ISO-8601 ↗ -Format (inkl. Zeitzonen-Offset) eingegrenzt:

Ohne Angabe von from/to liefert der Dienst die zuletzt verfügbaren Werte.

Die vollständige technische Beschreibung der Schnittstelle steht zusätzlich als OpenAPI-Spezifikation (YAML) zum Download bereit.

Referenz

• Antwortaufbau
• Endpunkte
  • GET /stations
  • GET /stations/{stationId}/parameters
  • GET /stations/{stationId}/parameters/{parameterId}/values
• Datentypen
  • Meta
  • Messstellen (Stationen)
  • Parameter
  • OperationalStatus
  • Value
  • Error
• Fehlerantworten
• Haftung und Lizenz

Antwortaufbau

Jede Antwort ist ein JSON-Objekt mit den beiden Eigenschaften meta und data. meta enthält allgemeine Informationen zu API, Herausgeber und Lizenz und ist in jeder Antwort (auch im Fehlerfall) vorhanden. data enthält die eigentliche Nutzlast – je nach Endpunkt eine Liste von Messstellen, Parametern oder Werten bzw. im Fehlerfall ein Fehlerobjekt.

{
  "meta": {
    "title": "PEGELONLINE HydroDaten API",
    "version": "0.1.0",
    "publisherName": "Generaldirektion Wasserstraßen und Schifffahrt (GDWS)",
    "licenseName": "DL-DE->Zero-2.0",
    "licenseUrl": "https://www.govdata.de/dl-de/zero-2-0"
  },
  "data": [ ... ]
}

In den folgenden Beispielen wird der gleichbleibende meta-Block mit "meta": { ... } abgekürzt.

Endpunkte

GET /stations

Gibt eine Liste der Messstellen zurück.

Parameter	In	Pflicht	Beschreibung
ids	Query	nein	Filtert nach mehreren Messstellen-IDs (kommagetrennt, eindeutige UUIDs).

Antwort 200: Objekt mit meta und data als Liste von Messstellen (Stationen). Mögliche Fehler: 400, 500.

{
  "meta": { ... },
  "data": [
    {
      "id": "a0af41ce-1899-4192-bc70-2fe66581bc8b",
      "name": "Teststation",
      "number": "123456",
      "state": "DE-BW",
      "operator": "Wasserstraßen- und Schifffahrtsamt (WSA) Rhein",
      "operatorUrl": "https://www.wsa-rhein.wsv.de/",
      "url": "https://...",
      "coordinates": { "lat": 52.5163, "lon": 13.3777 },
      "referenceElevation": { "value": 41.16, "unit": "m", "unitDisplay": "m NHN" },
      "waterBodyName": "Regnitz",
      "riverLocation": { "riverKilometre": 426.2, "stationingOrigin": "source" }
    }
  ]
}

GET /stations/{stationId}/parameters

Gibt eine Liste aller verfügbaren Parameter einer Messstelle zurück.

Parameter	In	Pflicht	Beschreibung
stationId	Pfad	ja	Eindeutige Kennung der Messstelle (UUID).
ids	Query	nein	Filtert nach Parameter-IDs (kommagetrennt).

Antwort 200: Objekt mit meta und data als Liste von Parameter. Mögliche Fehler: 400, 500.

{
  "meta": { ... },
  "data": [
    {
      "id": "water-level-rel-15min",
      "name": "Wasserstand , relativ",
      "interval": "PT15M",
      "availability": [
        { "start": "2020-01-01T00:00:00+01:00", "end": "2025-01-31T23:59:59+01:00" }
      ],
      "unitDisplay": "cm",
      "procedure": "measured",
      "status": { "condition": "operational", "message": null }
    }
  ]
}

GET /stations/{stationId}/parameters/{parameterId}/values

Gibt eine Zeitreihe von Messwerten für einen Parameter zurück. Unterstützt die Filterung nach Zeitraum.

Parameter	In	Pflicht	Beschreibung
stationId	Pfad	ja	Eindeutige Kennung der Messstelle (UUID).
parameterId	Pfad	ja	Eindeutige Kennung des Parameters, z. B. W.
from	Query	nein	Startzeitpunkt im ISO-8601-Format inkl. Zeitzone, z. B. 2025-01-01T00:00:00+01:00.
to	Query	nein	Endzeitpunkt im ISO-8601-Format inkl. Zeitzone, z. B. 2025-01-31T23:59:59+01:00.

Antwort 200: Objekt mit meta und data als Liste von Value. Mögliche Fehler: 400, 500.

{
  "meta": { ... },
  "data": [
    { "timestamp": "2025-01-27T12:00:00+01:00", "value": 287 },
    { "timestamp": "2025-01-27T12:15:00+01:00", "value": 289 },
    { "timestamp": "2025-01-27T12:30:00+01:00", "value": 291 }
  ]
}

Datentypen

Meta

Metadaten-Block mit allgemeinen Informationen. In jeder Antwort enthalten.

Feld	Typ	Pflicht	Beschreibung
title	string	ja	Titel/Name der API oder des Responses.
version	string	ja	Versionsnummer der API.
publisherName	string	ja	Name der bereitstellenden und veröffentlichenden Organisation.
licenseName	string	ja	Name der Daten-Lizenz.
licenseUrl	string	ja	URL zur Lizenzbeschreibung.

Messstellen (Stationen)

Messstellen bzw. Stationen oder Pegel an Flüssen, Seen und anderen Oberflächengewässern.

Feld	Typ	Pflicht	Beschreibung
id	string (UUID)	ja	Eindeutige unveränderliche Id der Messstelle zur Verwendung in URLs.
name	string	ja	Name der Messstelle.
waterBodyName	string	ja	Name des Gewässers.
number	string	nein	Nummer der Messstelle, sofern abweichend von der ID.
state	string	nein	Kürzel des Bundeslandes nach ISO 3166-2:DE.
operator	string	nein	Name des Messstellenbetreibers.
operatorUrl	string	nein	Webpräsenz des Messstellenbetreibers.
url	string	nein	Direkte URL zur Messstelle.
coordinates	object	nein	Geographische Koordinaten mit lat (Breite) und lon (Länge), jeweils number in WGS-84 (also GPS Koordinaten).
referenceElevation	object	nein	Bezugshöhe der Messstelle (der Pegelnullpunkt) mit value (number), unit (UCUM-Code) und unitDisplay.
riverLocation	object	nein	Lage am Gewässer mit riverKilometre (number) also der Kilometer an der Wasserstraße und stationingOrigin (source (Kilometer an der Wasserstraße steigt flussabwärts) | mouth (Kilometer an der Wasserstraße steigt flussaufwärts)).

Parameter

Informationen zur Messreihe und zur physikalischen Messgröße.

Feld	Typ	Pflicht	Beschreibung
id	string	ja	Eindeutige unveränderliche Id des Parameters zur Verwendung in URLs.
name	string	ja	Name/Bezeichnung des Parameters.
interval	string (ISO-8601 duration)	nein	Zeitlicher Abstand zwischen aufeinanderfolgenden Messungen, z. B. PT15M (alle 15 Minuten).
availability	array	nein	Zeitspannen, in denen Daten verfügbar sind; je Eintrag start und end (date-time).
unitDisplay	string	nein	Benutzerfreundliche Anzeige der Einheit (z. B. m³/s, °C).
procedure	string (enum)	nein	Verfahren zur Werterzeugung: measured, manual oder predicted.
status	OperationalStatus	nein	Aktueller Betriebsstatus des Parameters.

OperationalStatus

Informationen zum aktuellen Betriebsstatus eines Parameters.

Feld	Typ	Pflicht	Beschreibung
condition	string (enum)	ja	Betriebszustand: operational (normale Funktion) oder impaired (beeinträchtigte Funktion).
message	string	ja	Beschreibung des aktuellen Status, der Störung oder von Wartungsarbeiten.

Value

Wert mit Zeitstempel.

Feld	Typ	Pflicht	Beschreibung
timestamp	string (date-time)	ja	Zeitstempel des Wertes im ISO-8601-Format mit Zeitzone.
value	number (nullable)	ja	Der numerische Messwert; kann null sein, wenn kein Wert vorliegt.

Error

Standardisierte Fehlerantwort mit Meta-Informationen.

Feld	Typ	Pflicht	Beschreibung
meta	Meta	ja	Metadaten-Block.
data.status	integer	ja	Optionaler HTTP-Statuscode des Fehlers.
data.code	string	ja	Fehlercode zur Identifikation des Fehlertyps, z. B. BAD_REQUEST.
data.message	string	ja	Menschenlesbare Fehlermeldung.

Fehlerantworten

Fehler werden mit dem passenden HTTP-Statuscode und einem Error-Objekt ausgeliefert.

400 Bad Request

Die Anfrage ist fehlerhaft oder ungültig (allgemeiner Client-Fehler).

{
  "meta": { ... },
  "data": {
    "status": 400,
    "code": "BAD_REQUEST",
    "message": "Die Anfrage ist fehlerhaft oder ungültig"
  }
}

404 Not Found

Die angeforderte Ressource existiert nicht.

{
  "meta": { ... },
  "data": {
    "status": 404,
    "code": "NOT_FOUND",
    "message": "Die angeforderte Ressource existiert nicht"
  }
}

500 Internal Server Error

Ein allgemeiner, unerwarteter Serverfehler ist aufgetreten.

{
  "meta": { ... },
  "data": {
    "status": 500,
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Ein interner Serverfehler ist aufgetreten"
  }
}

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.