openapi: 3.0.3
info:
  title: HydroDaten API Standard - Basis
  version: '1.0_20260416'
  description: >-
    Diese OpenAPI-Spezifikation für hydrologische Daten des Projekts "HydroDaten API Standard (HyDAS)"  dient als Muster für die Implementierung von Datenschnittstellen (REST-API, öffentlich oder kundenspezifisch) in den deutschen Bundesländern, Bundesinstitutionen und weiteren Datenanbietern. Sie legt grundlegende Strukturen und Konventionen zur Bereitstellung hydrologischer Messdaten (z.B. Wasserstände) fest und bildet die technische Basis für zukünftige fachliche Erweiterungen, etwa in den Bereichen Niederschlag und Wasserqualität.


    Dies ist die Basis-Variante des HydroDaten API Standard (HyDAS) für einen vereinfachten Einstieg. Sie enthält nur 3 Endpunkte (/stations, /parameters und /values) und beschränkt sich auf das JSON-Format ohne Authentifizierung, Caching oder Pagination.


    Für die vollständige Spezifikation mit allen Endpunkten und Features siehe die erweiterte Variante.

    ## Hintergrund

    Der Bedarf nach einer bundesweiten Bereitstellung aktueller hydrologischer Pegel-Messwerte, insbesondere Wasserstände, ist groß und durch gesetzliche Vorgaben gestützt. Die föderale Zuständigkeit erschwert den Zugriff auf diese Daten, da sie von jedem Bundesland anders erfasst werden. Eine zentrale Anlaufstelle für Pegeldaten fehlt, was den Zugang kompliziert.


    Um den Kunden und den Datenaustausch zwischen Bundesländern zu erleichtern, wurde die Idee einer einheitlichen Spezifikation entwickelt. Diese definiert Struktur, Benennung und Antwortformate und richtet sich an alle Bundesländer und Datenanbieter. Sie dient als Vorlage für die Umsetzung von Schnittstellen (REST-API) und soll breit angewendet werden.


    Ziel ist es, den bundesweiten Zugang zu hydrologischen Daten zu vereinfachen und eine Grundlage für interoperable Fachanwendungen sowie den Datenaustausch zwischen Bund, Ländern und Dritten zu schaffen.


    Die Spezifikation entstand im Rahmen des Projekts "HydroDaten API", das Teilnehmer aus verschiedenen Bundesländern, Mitglieder der Bund/Länder-Arbeitsgemeinschaft (LAWA) und PEGELONLINE (Wasserstraßen- und Schifffahrtsverwaltung des Bundes) umfasst.

    ## Verwendung

    Die Spezifikation definiert Endpunkte, Datenstrukturen und Antwortformate. Sie dient zur Implementierung, Validierung und Dokumentation von Schnittstellen, die diesem Standard entsprechen. Zudem eignet sich die Spezifikation zur Validierung entwickelter APIs sowie zur Erstellung von Client- und Server-Stubs, die den Standard ebenfalls erfüllen.


    Weitere Informationen finden Sie in der [API-Guideline](https://dev.hochwasserzentralen.de/hydrodaten-api/guide) zur Verwendung des HydroDaten API Standards.
  x-logo:
    url: ''
servers:
- url: https://dev.hochwasserzentralen.de/hydrodaten-api/demo-basic/v1
  description: 'Demo-API (Basis)'
tags:
- name: Stationen
  description: >-
    Messstationen wie Oberflächengewässermessstationen, Grundwassermessstationen oder meteorologische Messstationen
- name: Parameter
  description: >-
    An einer Messstation verfügbare Messparameter (z.B. Wasserstand, Abfluss, Lufttemperatur) inklusive Einheit und Messintervall.
- name: Werte
  description: >-
    Messwerte (z.B. Wasserstände, Abflüsse, Temperaturen) mit Zeitstempeln und optionalen Qualitäts-Flags
paths:
  /stations:
    get:
      summary: Liste von Messstationen
      description: >-
        Gibt eine Liste der Messstationen zurück (Oberflächengewässermessstationen, Grundwassermessstationen oder Meteorologische Messstationen).
      operationId: getStations
      security:
      - {}
      tags:
      - Stationen
      parameters:
      - name: ids
        in: query
        required: false
        description: Filtert nach mehreren Messstations-IDs (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: waterBodyIds
        in: query
        required: false
        description: Filtert nach Gewässer-IDs (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: states
        in: query
        required: false
        description: Filtert nach Bundeslandkürzeln (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      responses:
        '200':
          description: Antwort mit Liste der Messstationen.
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  data:
                    type: array
                    uniqueItems: true
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/SurfaceWaterStation'
                      - $ref: '#/components/schemas/GroundwaterStation'
                      - $ref: '#/components/schemas/MeteorologicalStation'
                      discriminator:
                        propertyName: type
                        mapping:
                          surfaceWater: '#/components/schemas/SurfaceWaterStation'
                          groundwater: '#/components/schemas/GroundwaterStation'
                          meteorological: '#/components/schemas/MeteorologicalStation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/parameters:
    get:
      summary: Liste aller Parameter einer Messstation
      description: Gibt eine Liste aller verfügbaren Messparameter einer Messstation zurück.
      operationId: getStationParameters
      security:
      - {}
      tags:
      - Parameter
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: ids
        in: query
        required: false
        description: Filtert nach Parameter-IDs (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      responses:
        '200':
          description: Antwort mit Liste der Parameter
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  data:
                    type: array
                    uniqueItems: true
                    items:
                      $ref: '#/components/schemas/Parameter'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/parameters/{parameterId}/values:
    get:
      summary: Werte abrufen
      description: Gibt eine Zeitreihe von Messwerten für einen Parameter zurück. Unterstützt Filterung nach Zeitraum.
      operationId: getParameterValues
      security:
      - {}
      tags:
      - Werte
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: parameterId
        in: path
        required: true
        description: Eindeutige Kennung des Parameters
        schema:
          type: string
          example: water-level-rel-15min
      - name: from
        in: query
        required: false
        description: >-
          Startzeitpunkt der auszuliefernden Werte im ISO 8601 Format (inkl. Zeitzone), z. B. 2025-01-01T00:00:00+01:00
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        description: >-
          Endzeitpunkt der auszuliefernden Werte im ISO 8601 Format (inkl. Zeitzone), z. B. 2025-01-31T23:59:59+01:00
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Antwort mit Zeitreihe von Messwerten
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  data:
                    type: array
                    uniqueItems: true
                    items:
                      $ref: '#/components/schemas/Value'
              example:
                meta:
                  title: Projekt HydroDaten API
                  version: 1.0.0
                  publisherName: Beispiel-Landesamt
                  licenseName: dl-de/by-2-0
                  licenseUrl: https://www.govdata.de/dl-de/by-2-0
                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
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Meta:
      description: Metadaten-Block mit allgemeinen Informationen. Für jede API-Response erforderlich.
      type: object
      required:
      - title
      - version
      - publisherName
      - licenseName
      - licenseUrl
      properties:
        title:
          type: string
          description: Titel/Name der API oder des Responses
          example: Projekt HydroDaten API
        version:
          type: string
          description: Versionsnummer der API
          example: 1.0.0
        description:
          type: string
          description: Prägnante, aber informative Beschreibung der API oder des Responses (Beschreibung der Daten in Abschnitt `data`)
          example: API für hydrologische Stationsdaten, Mess- und Kennwerte
        descriptionUrl:
          type: string
          description: URL zur Beschreibung der API
          example: https://dev.hochwasserzentralen.de/hydrodaten-api/
        baseUrl:
          type: string
          description: Basis-URL der API
          example: https://api.example.io/v1
        publisherName:
          type: string
          description: Name der Organisation, die die API bereitstellt und veröffentlicht
          example: Hochwasservorhersagezentrale xy
        publisherEmail:
          type: string
          description: Emailadresse des Publishers
          example: kontakt@hochwasservorhersage.de
        licenseName:
          type: string
          description: Name der Daten-Lizenz
          example: CC BY 4.0
        licenseUrl:
          type: string
          description: URL zur Lizenzbeschreibung
          example: https://creativecommons.org/licenses/by/4.0/deed.de
        schemaUrl:
          type: string
          description: URL zur Schemadatei der Ressource
          example: https://api.example.io/v1/schema-stations.json
    OperationalStatus:
      title: Betriebsstatus
      description: >-
        Informationen zum aktuellen Betriebsstatus einer Messstation oder eines Parameters.
      type: object
      required:
      - condition
      - message
      properties:
        condition:
          type: string
          description: >-
            Kennzeichnung des Betriebszustand: `operational` = normale Funktion, `impaired` = unspezifische allgemeine Form der Beeinträchtigung, `decommissioned` = nicht mehr in Betrieb. Auch spezifischere Formen der Beeinträchtigung können angegeben werden (z.B. `sensor-malfunction` = Sensorausfall oder `maintenance` = Wartungsarbeiten )
          enum:
          - operational
          - impaired
          - decommissioned
          - unavailable
          - degraded
          - sensor-malfunction
          - communication-failure
          - power-outage
          - maintenance
          - construction
          - calibration
          - data-quality
          - environmental
          - offline
          - other
          example: operational
        message:
          type: string
          description: Beschreibung des aktuellen Status, der Störung oder Wartungsarbeiten
          example: Wegen einer Funktionsstörung liefert die Station aktuell keine Messwerte.
        since:
          type: string
          format: date-time
          description: Zeitpunkt seit dem der aktuelle Status gilt
          example: '2025-01-15T08:30:00+01:00'
        expectedEnd:
          type: string
          format: date-time
          description: Voraussichtlicher Zeitpunkt der Behebung bei Störungen oder Ende der Wartungsarbeiten
          example: '2025-01-16T14:00:00+01:00'
        contact:
          type: string
          description: Kontaktinformation für aktuelle Messwerte oder Rückfragen bei Störungen (z.B. Telefonnummer, E-Mail)
          example: 'email@pegel.de'
    BaseStation:
      x-internal: true
      description: Basisschema mit gemeinsamen Attributen aller Messstationen
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Eindeutige unveränderliche Id der Messstelle zur Verwendung in URLs
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
        name:
          type: string
          description: Name der Messstelle
          example: Teststation
        number:
          type: string
          description: Nummer der Messstelle, wenn diese sich von der ID nochmal unterscheidet. Kann ggf. weggelassen werden.
          example: '123456'
        type:
          type: string
          description: "Haupttyp der Messstelle. 'surfaceWater' = Oberflächengewässermessstation, 'groundwater' = Grundwassermessstation, 'meteorological' = Meteorologische Messstation. Sollte unbedingt aufgeführt werden, wenn unterschiedliche Stationsarten an den  Stationen-Endpunkten zurückgeliefert werden können."
          enum:
          - surfaceWater
          - groundwater
          - meteorological
          example: surfaceWater
        state:
          type: string
          description: Kürzel des Bundeslandes nach ISO 3166-2:DE oder des Staates nach ISO-3166-1-Kodierliste
          example: DE-BW
        operator:
          type: string
          description: Name des Messstellenbetreibers
          example: Wasserstraßen- und Schifffahrtsamt (WSA) Rhein
        operatorUrl:
          type: string
          description: Webpräsenz des Messstellenbetreibers
          example: https://www.wsa-rhein.wsv.de/
        dataProvider:
          type: string
          description: Name des Datenbereitstellers
          example: LUBW Baden-Württemberg
        dataProviderUrl:
          type: string
          description: Webpräsenz des Datenbereitstellers
          example: https://www.lubw.baden-wuerttemberg.de
        url:
          type: string
          description: Direkte URL zur Messstelle
          example: https://hvz-example.io/messstelle-1.html
        status:
          $ref: '#/components/schemas/OperationalStatus'
        remarks:
          type: string
          description: Bemerkung zur Station (Freitext)
          example: Der Pegel liegt im Rückstau der Staustufe Bittenheim/Donau.
        gaugingNetwork:
          type: string
          description: Nennung des Namens des Messnetzes
          example: GW-Stand
        coordinates:
          type: object
          required:
          - lat
          - lon
          properties:
            lat:
              type: number
              description: Wert der geographischen Breite
              example: 52.5163
            lon:
              type: number
              description: Wert der geographische Höhe
              example: 13.3777
            epsgCode:
              type: integer
              description: EPSG-Code des Koordinatenreferenzsystems der Koordinaten. Standardwert ist WGS 84 (EPSG:4326), welcher die größte Kompatibilität gewährleistet. Wenn nicht angegeben, wird WGS 84 angenommen.
              default: 4326
              example: 4326
        referenceElevation:
          type: object
          description: Höhe bzw. Bezugshöhe einer Station, bei Pegeln i.d.R. der Pegelnullpunkt.
          required:
          - value
          properties:
            value:
              type: number
              description: Absolute Höhe, üblicherweise in Höhe über dem Meeresspiegel
            unit:
              type: string
              description: Einheit der Höhe entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
              example: m
            unitDisplay:
              type: string
              description: Benutzerfreundliche Anzeige der Höhe ggf. mit Bezug zum Höhensystem
              example: m NHN
            epsgCode:
              type: integer
              description: EPSG-Code des Höhensystems. Standardwert ist DHHN 2016 (EPSG:7837).
              default: 7837
              example: 7837
        municipalityCode:
          type: integer
          description: Gemeindeschlüssel, z.B. Amtlichen Gemeindeschlüssel (AGS)
          example: 9763000
        predecessorId:
          type: string
          description: Eindeutige Id der (stillgelegten) Vorgänger-Messstelle im selben räumlichen Bereich
          example: 3f4a8c10-9b2e-4c5f-8af1-12ab34cd56ef
        successorId:
          type: string
          description: Eindeutige Id der Nachfolger-Messstelle im selben räumlichen Bereich
          example: 3f445c10-9b2e-4c5f-8af1-12ad34cd56f1
    SurfaceWaterStation:
      title: Pegel (Messstation Oberflächengewässer)
      description: |
        Pegel (Messstation Oberflächengewässer) - type: "surfaceWater"

        Messstation an Flüssen, Seen und anderen Oberflächengewässern.
      allOf:
      - $ref: '#/components/schemas/BaseStation'
      - type: object
        required:
        - waterBodyName
        properties:
          waterBodyId:
            type: string
            description: 'Gewässerkennzahl als eindeutige unveränderliche Id zur Verwendung in URLs. Vgl. https://de.wikipedia.org/wiki/Gewässerkennzahl_(Deutschland)#Wichtige_Gewässerkennzahlen'
            example: 242
          waterBodyName:
            type: string
            description: Name des Gewässers
            example: 'Regnitz'
          riverHierarchy:
            type: string
            description: Gewässerfolge (Einordnung des Gewässers in das Flusssystem)
            example: Regnitz - Main - Rhein - Nordsee
          riverBasinID:
            type: string
            description: Gebietskennzahl des (meist übergeordneten) Flussgebiets
            example: 2
          riverBasinName:
            type: string
            description: Name des (meist übergeordneten) Flussgebiets
            example: Rhein
          catchmentAreaSize:
            type: object
            description: Einzugsgebietsgröße des Pegels (oberirdisch)
            properties:
              value:
                type: number
                description: Wert für die Einzugsgebietsgröße
                example: 555.3
              unit:
                type: string
                description: Einheit der Einzugsgebietsgröße entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: km2
              unitDisplay:
                type: string
                description: Benutzerfreundliche Anzeige der Einheit (km²)
                example: km²
          riverLocation:
            type: object
            description: Lage des Pegels am Gewässer
            properties:
              riverKilometre:
                type: number
                description: Flusskilometer (Stationierung)
                example: 426.2
              stationingOrigin:
                type: string
                description: >-
                  Bezugspunkt der Stationierung (`riverKilometre`): `source` = von der Quelle flussabwärts gezählt, `mouth` = von der Mündung flussaufwärts gezählt.
                enum:
                  - source
                  - mouth
                example: source
              distanceFromMouthKm:
                type: number
                description: Entfernung von der Mündung in Kilometern
                example: 32.6
              lateralPosition:
                type: string
                description: Lage am Gewässer (links, Mitte, rechts) in Fließrichtung gesehen
                enum:
                  - bank-left
                  - mid-stream
                  - bank-right
                example: bank-left
    GroundwaterStation:
      title: Grundwassermessstelle (Messstation Grundwasser)
      description: |
        Grundwassermessstelle (Messstation Grundwasser) - type: "groundwater"

        Messstation zur Erfassung von v.a. Grundwasserständen.
      allOf:
      - $ref: '#/components/schemas/BaseStation'
      - type: object
        properties:
          groundSurfaceElevation:
            type: object
            description: Höhe der Geländeoberkante
            properties:
              value:
                type: number
                description: Höhenwert der Geländeoberkante
                example: 445.18
              unit:
                type: string
                description: Einheit der Höhe der Geländeoberkante entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
              unitDisplay:
                type: string
                description: Benutzerfreundliche Anzeige der Höhe der Geländeoberkante, ggf. mit Bezug zum Höhensystem
                example: m NHN
              epsgCode:
                type: integer
                description: EPSG-Code des Höhensystems. Standardwert ist DHHN 2016 (EPSG:7837).
                default: 7837
                example: 7837
          filterTopOfScreen:
            type: object
            description: Beginn des Filters unter der Geländeoberkante
            properties:
              value:
                type: number
                description: Relativer Wert für den Beginn des Filters unter der Geländeoberkante
                example: 12
              unit:
                type: string
                description: Einheit für den Beginn des Filters unter der Geländeoberkante entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
          filterBottomOfScreen:
            type: object
            description: Ende des Filters unter der Geländeoberkante
            properties:
              value:
                type: number
                description: Relativer Wert für das Ende des Filters unter der Geländeoberkante
                example: 13.95
              unit:
                type: string
                description: Einheit für das Ende des Filters unter der Geländeoberkante entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
          aquifer:
            type: object
            description: Angabe zu den hydraulischen Druckverhältnissen
            properties:
              name:
                type: string
                description: Name Grundwasserkörper in dem die Messstelle verfiltert ist
                example: Panketalgrundwasserleiter (GWL 1.2)
              type:
                type: string
                description: Angabe zu den hydraulischen Druckverhältnissen
                example: ungespannt
          depthOfTheObservationWell:
            type: object
            description: Endtiefe der Grundwassermessstelle (relativ zur Geländeoberkante)
            properties:
              value:
                type: number
                description: Wert der Endtiefe der Grundwassermessstelle
                example: 10
              unit:
                type: string
                description: Einheit der Endtiefe der Grundwassermessstelle entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
          subarea:
            type: object
            properties:
              id:
                type: integer
                description: Nummer des hydrogeologischen Teilraums oder des Einzugsgebiets
                example: 1315
              name:
                type: string
                description: Name des hydrogeologischen Teilraums oder des Einzugsgebiets
                example: Panketal
    MeteorologicalStation:
      title: Wetterstation (Messstation Meteorologie)
      description: |
        Wetterstation (Messstation Meteorologie) - type: "meteorological"
      allOf:
      - $ref: '#/components/schemas/BaseStation'
    Parameter:
      title: Parameter
      description: Informationen zur Messreihe und zur physikalischen Messgröße
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Eindeutige unveränderliche Id des Parameters zur Verwendung in URLs. Kann auch für die fachliche Identifikation des Parameters/Messreihe genutzt werden.
          example: water-level-rel-15min
        name:
          type: string
          description: Name/Bezeichnung des Parameter
          example: Wasserstand , relativ
        description:
          type: string
          description: Ausführliche Beschreibung des Parameters und seiner Bedeutung
          example: Relativer Wasserstand in Zentimetern
        interval:
          type: string
          format: duration
          description: "Zeitlicher Abstand zwischen aufeinanderfolgenden Messungen bzw. Datenpunkten als ISO-8601 'duration' (z.B. 'PT15M' bedeutet alle 15 Minuten wird ein Wert erfasst)."
          example: PT15M
        availability:
          type: array
          description: Zeitspannen, in denen Daten verfügbar sind
          items:
            type: object
            required:
            - start
            - end
            properties:
              start:
                type: string
                format: date-time
                description: Beginn der Datenverfügbarkeit
              end:
                type: string
                format: date-time
                description: Ende der Datenverfügbarkeit
        observedProperty:
          type: string
          description: Die physikalische Eigenschaft, die gemessen wird
          enum:
          - water-level-rel
          - water-level-abs
          - discharge
          - water-temperature
          - flow-rate
          - precipitation
          - snow-depth
          - snow-water-equivalent
          - air-temperature
          - dew-point
          - relative-humidity
          - wind-speed
          - wind-direction
          - solar-radiation
          - sunshine-duration
          - air-pressure
          - groundwater-level-rel
          - groundwater-level-abs
          - groundwater-temperature
          - spring-discharge
        unit:
          type: string
          description: Standardisierte ASCII UCUM-Einheitencodes (Unified Code for Units of Measure). Siehe https://units-of-measurement.org/
          enum:
          - cm
          - m
          - m3/s
          - Cel
          - m/s
          - mm
          - '%'
          - deg
          - W/m2
          - min
          - hPa
          - L/s
          example: cm
        unitDisplay:
          type: string
          description: Benutzerfreundliche Anzeige der Einheit (m³/s, °C, usw.)
          example: m³/s
        procedure:
          type: string
          description: Verfahren zur Werterzeugung
          enum:
          - measured
          - manual
          - calculated
          - simulated
          - predicted
        aggregationType:
          type: string
          description: "Art der Aggregation der Messwerte. 'instantaneous' für Momentanwerte zu einem bestimmten Zeitpunkt, 'average' für Mittelwerte über einen Zeitraum, 'maximum' und 'minimum' für Extremwerte innerhalb eines Zeitraums, 'cumulative' für aufsummierte Werte (z.B. Niederschlagssummen)"
          enum:
          - instantaneous
          - average
          - maximum
          - minimum
          - cumulative
        aggregationDuration:
          type: string
          format: duration
          description: "Zeitraum über den die Messwerte aggregiert werden (z.B. 'PT15M' bedeutet Mittelwert über 15 Minuten). Wird nur bei aggregierten Messungen (mean, maximum, minimum, cumulative) verwendet. Nicht zu verwechseln mit 'interval', welches den Abstand zwischen aufeinanderfolgenden Messungen definiert."
          example: PT15M
        status:
          $ref: '#/components/schemas/OperationalStatus'
    Value:
      title: Wert mit Zeitstempel
      description: Wert mit Zeitstempel und optionalen Flags
      type: object
      required:
      - timestamp
      - value
      properties:
        timestamp:
          type: string
          format: date-time
          description: Datums- Zeitstempel des Wertes im ISO 8601 Format mit Zeitzone
          example: '2025-01-27T12:00:00+01:00'
        value:
          type: number
          nullable: true
          description: Der numerische Messwert
          example: 287
        quality:
          type: string
          description: Optionale Flags (z.B. Qualitätseinstufungen) für den Messwert
          enum:
          - good
          - suspect
          - estimate
          - poor
          - unchecked
          - missing
          example: good
    Error:
      description: Standardisierte Fehlerantwort mit Meta-Informationen
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: object
          description: Detaillierte Fehlerinformationen
          required:
          - code
          - message
          properties:
            status:
              type: integer
              description: Optionaler HTTP-Statuscode des Fehlers
              example: 404
            code:
              type: string
              description: Fehlercode zur Identifikation des Fehlertyps
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              description: Menschenlesbare Fehlermeldung
              example: Die angeforderte Ressource existiert nicht
            details:
              type: array
              description: Optionale zusätzliche Details zum Fehler, z.B. Fehler bei einzelnen Query-Parametern
              items:
                type: string
              example:
              - Station mit ID 'xyz' wurde nicht gefunden
  responses:
    BadRequest:
      description: "400 Bad Request - Die Anfrage ist fehlerhaft oder ungültig. Ein allgemeiner Fehler, wenn der Server die Anfrage aufgrund eines Client-Fehlers nicht verarbeiten kann."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 400
              code: BAD_REQUEST
              message: Die Anfrage ist fehlerhaft oder ungültig
              details:
              - Der Parameter 'from' hat ein ungültiges Datumsformat
    NotFound:
      description: "404 Not Found - Die angeforderte Ressource existiert nicht. Einer der häufigsten Statuscodes."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 404
              code: NOT_FOUND
              message: Die angeforderte Ressource existiert nicht
              details:
              - Station mit der ID 'a0af41ce-1899-4192-bc70-2fe66581bc8b' wurde nicht gefunden
    InternalServerError:
      description: "500 Internal Server Error - Ein allgemeiner Serverfehler ist aufgetreten. Der Server hat eine unerwartete Bedingung angetroffen."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 500
              code: INTERNAL_SERVER_ERROR
              message: Ein interner Serverfehler ist aufgetreten
              details:
              - Bitte versuchen Sie es später erneut
