HydroDaten API Standard

for Developers

Einführung

Diese Einführung führt Sie schrittweise durch die wichtigsten Konzepte und Funktionen des HydroDaten API Standard (HyDAS).

Die vollständige Dokumentation der Spezifikation finden Sie auf der Dokumentationsseite.
Vertiefende Informationen zur Umsetzung einer API finden sich in der Guideline.

Ressourcen-Überblick

Eine API nach dem Standard besteht aus vier Hauptressourcen, die hierarchisch miteinander verknüpft sind:

StationenMessstationen an Oberflächengewässern, Grundwassermessstellen oder Wetterstationen
ParameterPhysikalische Messgrößen und ihre Messreihen, die an Stationen erfasst werden (z.B. Wasserstand, Abfluss, Temperatur).
WerteMesswerte oder Vorhersagen für einen Parameter
KennwerteInformationen zu statistischen Maßzahlen, abgeleiteten Werten, gewässerkundlichen Hauptwerten oder Wasserstandsmarken

Hierarchie Messwerte: Station → Parameter → Werte
Beispiel: Pegel Köln/Rhein (Station) erfasst Wasserstand (Parameter) mit Messwerten alle 15 Minuten (Werte).

Hierarchie Kennwerte: Station → Kennwerte
Beispiel: Am Pegel Köln/Rhein (Station) gibt es hydrologische Hauptwerte (Kennwerte).

Basisversion und erweiterte Version

Der HydroDaten API Standard (HyDAS) ist in zwei Varianten verfügbar:

BASIS Basisversion

Einstiegsversion als Grundlage, um eine Implementation des Standards zu erstellen:

3 der 4 Hauptressourcen (Endpunkte):
/stations, /parameters und /values, keine Kennwerte
Nur JSON-Format
Nur essentielle Query-Parameter
Keine Authentifizierung, kein Caching, keine Pagination

Dokumentation Download OpenAPI Spezifikation

ERWEITERT Erweiterte Version

Zusätzliche Features dienen als optionale Elemente für eine Implementation des Standards nach dem Baukastenprinzip:

Alle 4 Hauptressourcen (Endpunkte):
/stations, /parameters, /values und /characteristics sowie weitere 5 Endpunkte wie /health
Mehrere Formate (JSON, CSV und GeoJSON)
Weitere Query-Parameter
Authentifizierung, HTTP-Caching, Pagination, Sortierung, Feldauswahl, HATEOAS-Links usw.

Dokumentation Download OpenAPI Spezifikation

1. Schnellstart - Erste API-Anfrage BASIS ERWEITERT

Die einfachste Anfrage ruft eine Liste aller Messstationen ab.

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1/stations

Response:

{
  "meta": {
    "title": "Meine HydroDaten API",
    "version": "1.0.0",
    "publisherName": "Meine HydroDaten API von XYZ",
    "licenseName": "CC BY 4.0",
    ...
  },
  "data": [
    {
      "id": "a0af41ce-1899-4192-bc70-2fe66581bc8b",
      "name": "Teststation",
      "type": "surfaceWater",
      "state": "BW",
      "coordinates": {
        "lat": 52.5163,
        "lon": 13.3777
      },
      ...
    }
  ]
}

Die Antwort enthält Metadaten zur API (meta) und die eigentlichen Stationsdaten (data).

2. Response-Struktur verstehen

Jede API-Antwort folgt einer einheitlichen Struktur mit zwei BASIS oder drei ERWEITERT Hauptsektionen:

`meta` - API-Informationen BASIS ERWEITERT

Enthält Metadaten über die API selbst:

{
  "meta": {
    "title": "Meine HydroDaten API",
    "version": "1.0.0",
    "description": "Meine HydroDaten API für hydrologische Stationsdaten",
    "publisherName": "Meine HydroDaten API von XYZ",
    "licenseName": "CC BY 4.0",
    "licenseUrl": "https://creativecommons.org/licenses/by/4.0/"
  }
}

`links` - HATEOAS Navigation ERWEITERT

Bietet Links zu verwandten Ressourcen für einfache Navigation (HATEOAS-Prinzip: "Hypermedia as the Engine of Application State"):

{
  "links": [
    {
      "rel": "self",
      "href": "http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations"
    },
    {
      "rel": "station",
      "href": "http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/{stationId}"
    }
  ]
}

`data` - Die eigentlichen Daten BASIS ERWEITERT

Enthält die abgefragten Ressourcen als Array (bei Listen) oder Objekt (bei Einzelressourcen).

Mehr Details: Guideline → Metasektion und Guideline → HATEOAS-Prinzip

3. Stationen filtern BASIS ERWEITERT

Mit Query-Parametern können Sie die Stationsliste nach verschiedenen Kriterien filtern:

Nach Bundesland filtern:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1/stations?states=DE-BW

Nach Gewässer filtern:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1/stations?waterBodyIds=2

Hinweis: waterBodyIds=2 ist die Gewässerkennzahl für den Rhein

Mehrere Filter kombinieren:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1/stations?states=DE-NW,DE-BW&waterBodyIds=2

Liefert alle Stationen in Nordrhen-Westfalen und Baden-Württemberg am Rhein.

4. Geografische Suche ERWEITERT

Finden Sie Stationen in einem geografischen Gebiet oder Umkreis:

Bounding Box (rechteckiger Bereich):

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?bbox=6.0,47.0,9.0,51.0

Format: minLon,minLat,maxLon,maxLat (Koordinaten in WGS 84)

Umkreissuche:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?near=13,52,100

Format: lon,lat,radius - findet alle Stationen im Umkreis von 100 km um den Punkt 13° Ost, 52° Nord.

Mehr Details: Guideline → Koordinatenumwandlung

5. Einzelne Station abrufen ERWEITERT

Rufen Sie detaillierte Informationen zu einer spezifischen Station ab:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b

Response:

{
  "meta": {...},
  "links": [...],
  "data": {
    "id": "a0af41ce-1899-4192-bc70-2fe66581bc8b",
    "name": "Teststation",
    "type": "surfaceWater",
    "state": "DE-BW",
    "operator": "Regierungspräsidium xy",
    "waterBodyId": "2",
    "waterBodyName": "Rhein",
    "coordinates": {
      "lat": 52.5163,
      "lon": 13.3777
    }
  }
}

Es sind verschiedene Stationstypen mit unterschiedlichen Attribute vorgesehen:

type=surfaceWater (Oberflächengewässer)
type=groundwater (Grundwasser)
type=meteorological (Wetter)

Gilt nur wenn unterschiedliche Stationstypen unter /stations abrufbar sind.

6. Verlinkung oder Einbettung von Ressourcen ERWEITERT

Bieten Sie die Links in der Response an, um dem API-Client die Möglichkeit zu bieten, zu verwandten Ressourcen zu navigieren - das ist das HATEOAS-Prinzip.

Response mit URL-Templates zu verknüpften Ressourcen der jeweiligen Station:

{
    "meta": {...},
    "links": [
        {
            "rel": "self",
            "href": "http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b"
        },
        {
            "rel": "parameters",
            "href": "http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters"
        },
        {
            "rel": "values",
            "href": "http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/{parameterId}/values",
        },
        {
            "rel": "characteristics",
            "href": "http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/characteristics"
        }
    ],
    "data": {...}
}

Alternative: Parameter oder Kennwerte direkt einbetten per Query-Parameter include: ERWEITERT

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b?include=parameters

Response mit eingebetteten Parametern:

{
  "meta": {...},
  "links": [
    {...}
  ],
  "data": {
    "id": "a0af41ce-1899-4192-bc70-2fe66581bc8b",
    "name": "Teststation",
    ...
    "parameters": [
      {
        "id": "water-level-rel-15min",
        "name": "Wasserstand, relativ",
        "observedProperty": "water-level-rel",
        "unit": "cm",
        "interval": "PT15M",
        "availability": [
          {
            "start": "2020-01-01T00:00:00+01:00",
            "end": "2025-12-31T23:59:59+01:00"
          }
        ]
      },
      {
        "id": "discharge-15min",
        "name": "Abfluss",
        "observedProperty": "discharge",
        "unit": "m³/s",
        "interval": "PT15M",
        "availability": [
          {
            "start": "2020-01-01T00:00:00+01:00",
            "end": "2025-12-31T23:59:59+01:00"
          }
        ]
      }
    ]
  }
}

7. Parameter und Messreihen BASIS ERWEITERT

Parameter beschreiben die physikalischen Messgrößen und ihre Zeitreihen, die an Stationen erfasst werden (z.B. Wasserstand, Abfluss, Temperatur).

Parameter einer Station abrufen:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters

Response:

{
  "meta": {...},
  "data": [
    {
      "id": "water-level-rel-15min",
      "name": "Wasserstand, relativ",
      "observedProperty": "water-level-rel",
      "unit": "cm",
      "interval": "PT15M",
      "availability": [
        {
          "start": "2020-01-01T00:00:00+01:00",
          "end": "2025-12-31T23:59:59+01:00"
        }
      ]
    }
  ]
}

Wichtige Eigenschaften:

observedProperty: Die physikalische Eigenschaft, die gemessen wird (z.B. water-level-rel, discharge, water-temperature)
unit: Maßeinheit der Werte (UCUM-Standard: cm, m³/s, deg)
interval: Messintervall zwischen einzelnen Werten als ISO 8601 Duration (PT15M = alle 15 Minuten)
availability: Zeitspannen, in denen Daten verfügbar sind

Einzelnen Parameter abrufen:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min

8. Werte abrufen BASIS ERWEITERT

Rufen Sie Zeitreihen von Messwerten oder Vorhersagen ab:

Letzte 10 Werte: ERWEITERT

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?recent=10

Bestimmter Zeitraum: BASIS ERWEITERT

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?from=2026-05-06T09:00:00+02:00&to=2026-05-06T11:00:00+02:00

Relative Zeitangabe (letzte 24 Stunden): ERWEITERT

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?last=P1D

Response:

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

ISO 8601 Zeitformat: Alle Zeitstempel folgen dem Format YYYY-MM-DDTHH:MM:SS+TZ mit Zeitzone (z.B. +01:00 für MEZ).

Mehr Details: Guideline → Zeitangaben

9. Große Datenmengen - Pagination ERWEITERT

Bei großen Datenmengen können Sie die Ergebnisse in Seiten aufteilen:

Ersten 50 Werte:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?limit=50&offset=0

Nächsten 50 Werte:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?limit=50&offset=0

Die Response kann entsprechend Pagination-Informationen im Meta-Block enthalten:

{
  "meta": {
    ...
    "pagination": {
      "total": 2847,
      "count": 100,
      "limit": 100,
      "offset": 0,
      "page": 1,
      "totalPages": 29,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  },
  "links": [
    {"rel": "self", "href": "...?limit=100&offset=0"},
    {"rel": "first", "href": "...?limit=100&offset=0"},
    {"rel": "next", "href": "...?limit=100&offset=100"},
    {"rel": "last", "href": "...?limit=100&offset=2800"}
  ],
  "data": [...]
}

Es können links angeboten werden (next, prev, first, last), um durch die Seiten zu navigieren.

Mehr Details: Guideline → Pagination

10. Sortierung & Feldauswahl ERWEITERT

Bieten sie Sortierung und optimierte Datenübertragung durch gezielte Feldauswahl an:

Sortierung

Aufsteigend sortieren:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?sort=name

Absteigend sortieren (mit Minus-Präfix):

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?sort=-name

Mehrfach-Sortierung:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?sort=state,-name

Sortiert erst nach Bundesland (aufsteigend), dann nach Name (absteigend).

Feldauswahl

Nur benötigte Felder abrufen:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?fields=id,name,coordinates

Verschachtelte Felder mit Punkt-Notation:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?fields=id,name,coordinates.lat,coordinates.lon

Response (nur ausgewählte Felder):

{
  "meta": {...},
  "data": [
    {
      "id": "a0af41ce-1899-4192-bc70-2fe66581bc8b",
      "name": "Teststation",
      "coordinates": {
        "lat": 52.5163,
        "lon": 13.3777
      }
    }
  ]
}

Kombination aller Parameter:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?fields=id,name&sort=name&limit=50

Mehr Details: Guideline → Feldauswahl, Guideline → Sortierung

11. Formate für verschiedene Anwendungen ERWEITERT

Der HydroDaten API Standard (HyDAS) unterstützt verschiedene Ausgabeformate für unterschiedliche Anwendungsfälle. Diese können per Query-Parameter oder Http-Header spezifiziert werden:

JSON (Standard)

Für Webanwendungen und API-Integrationen:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?format=application/json

CSV

Für Excel, Datenanalyse und Zeitreihen:

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?format=text/csv

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?format=text/csv

Beispiel CSV-Output:

id,name,type,state,operator,coordinates.lat,coordinates.lon,waterBodyName
a0af41ce-1899-4192-bc70-2fe66581bc8b,Teststation,surfaceWater,BW,Regierungspräsidium xy,52.5163,13.3777,Rhein

GeoJSON

Für Kartendarstellungen (Leaflet, Mapbox, QGIS):

GET http://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1/stations?format=application/geo+json

Response:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.3777, 52.5163]
      },
      "properties": {
        "id": "a0af41ce-...",
        "name": "Teststation",
        "type": "surfaceWater"
      }
    }
  ]
}

Hinweis: Bei GeoJSON ist die Koordinatenreihenfolge [longitude, latitude]

Alternative: Accept-Header

Statt Query-Parameter können Sie auch den HTTP Accept-Header verwenden:

Accept: text/csv
Accept: application/geo+json

Der format Query-Parameter hat Vorrang vor dem Accept-Header.

Mehr Details: Guideline → Content Negotiation

12. Cross-Origin Resource Sharing (CORS) BASIS ERWEITERT

CORS (Cross-Origin Resource Sharing) ermöglicht Browser-Anwendungen (Web-Apps), auf die API von anderen Domains aus zuzugreifen. Ohne CORS blockieren Browser aus Sicherheitsgründen solche Anfragen. Web-Anwendungen können somit direkt vom Browser aus API-Anfragen stellen

CORS wird nicht in der API selbst, sondern auf Webserver-Ebene (Apache, nginx, Load Balancer) konfiguriert. Folgende HTTP-Header müssen gesetzt werden:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS

Sicherheitshinweise:

Öffentliche APIs: Wildcard * ist bei APIs ohne Authentifizierung akzeptabel
Geschützte APIs: Bei APIs mit Authentifizierung sollten nur spezifische Domains erlaubt werden (keine Wildcard)

Mehr Details: Guideline → CORS Konfiguration

13. Vorgehen für eine Implementation des HydroDaten API Standards (HyDAS)

Open-API Spezifikation der Basis-Variante als Grundlage verwenden, anpassen und ggf. mit Elementen der erweiterten Variante ergänzen
Optionale Attribute und weitere Elemente entfernen, welche im jeweiligen Datenangebot nicht zur Verfügung stehen
Weitere Anpassung des Standards mit zusätzlichen Attributen, Query-Parametern, Formaten usw. je nach Datenangebot
Erstellung einer Grundimplementation für die jeweilige Zielplattform z.B. mit OpenAPI Generator oder mittels KI basierend auf einer angepassten OpenAPI Spezifikation
Implementation der API
Einrichtung der CORS Header im Server
Einfaches Rate-Limiting einrichten (Schutz des Dienstes)
Prüfung der API auf Konformität mittels Swagger Editor oder Postman
Ggf. Dokumentation aus angepasster OpenAPI Spezifikation generieren und veröffentlichen
Überwachung der API mittels UptimeRobot oder Pingdom

14. Nächste Schritte

Sie haben nun die Grundlagen des HyDAS kennengelernt. Hier finden Sie weiterführende Ressourcen:

DokumentationInteraktive API-Dokumentation in Basis und erweiterter Variante mit allen Endpunkten, Parametern und Schemas.
Zur Dokumentation
GuidelineImplementierungshinweise, Best Practices, Versionierung, Sicherheit und Testing.
Zur Guideline
Aktive APIsÜbersicht über Bundesländer und Institutionen, die den Standard bereits implementiert haben.
Zu den APIs

Weitere Themen

Kennwerte: Statistische Maßzahlen, Hauptwerte und Schwellenwerte abrufen ERWEITERT
Health-Check: API-Verfügbarkeit und Status überwachen ERWEITERT
Authentifizierung: API-Keys, OAuth 2.0 und Basic Auth ERWEITERT
Caching: ETag und Cache-Control für effiziente Datenabfrage ERWEITERT

Alle diese Themen finden Sie ausführlich in der Guideline beschrieben.

Einführung

Ressourcen-Überblick

Stationen

Parameter

Werte

Kennwerte

Basisversion und erweiterte Version

BASIS Basisversion

ERWEITERT Erweiterte Version

1. Schnellstart - Erste API-Anfrage BASIS ERWEITERT

2. Response-Struktur verstehen

meta - API-Informationen BASIS ERWEITERT

links - HATEOAS Navigation ERWEITERT

data - Die eigentlichen Daten BASIS ERWEITERT

3. Stationen filtern BASIS ERWEITERT

4. Geografische Suche ERWEITERT

5. Einzelne Station abrufen ERWEITERT

6. Verlinkung oder Einbettung von Ressourcen ERWEITERT

7. Parameter und Messreihen BASIS ERWEITERT

8. Werte abrufen BASIS ERWEITERT

9. Große Datenmengen - Pagination ERWEITERT

10. Sortierung & Feldauswahl ERWEITERT

Sortierung

Feldauswahl

11. Formate für verschiedene Anwendungen ERWEITERT

JSON (Standard)

CSV

GeoJSON

Alternative: Accept-Header

12. Cross-Origin Resource Sharing (CORS) BASIS ERWEITERT

13. Vorgehen für eine Implementation des HydroDaten API Standards (HyDAS)

14. Nächste Schritte

Dokumentation

Guideline

Aktive APIs

Weitere Themen

`meta` - API-Informationen BASIS ERWEITERT

`links` - HATEOAS Navigation ERWEITERT

`data` - Die eigentlichen Daten BASIS ERWEITERT