openapi: 3.0.3
info:
  title: HydroDaten API - PEGELONLINE
  version: '0.1.0'
  description: 'PEGELONLINE API nach HydroDaten API Standard (https://dev.hochwasserzentralen.de/hydrodaten-api/)'
  x-logo:
    url: ''
servers:
- url: https://pegelonline-testprev.wsv.de/api/v1
  description: ''
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
      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:
                      $ref: '#/components/schemas/SurfaceWaterStation'
        '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: 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:
                  - 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
        publisherName:
          type: string
          description: Name der Organisation, die die API bereitstellt und veröffentlicht
          example: Hochwasservorhersagezentrale xy
        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
    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` = beeinträchtigte Funktion
          enum:
            - operational
            - impaired
          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.
    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'
        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/
        url:
          type: string
          description: Direkte URL zur Messstelle
        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
        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
    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:
            waterBodyName:
              type: string
              description: Name des Gewässers
              example: 'Regnitz'
            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
    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
        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
        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
            - predicted
        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
    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:
            - status
            - code
            - message
          properties:
            status:
              type: integer
              description: 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
  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: 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:
              status: 400
              code: BAD_REQUEST
              message: Die Anfrage ist fehlerhaft oder ungültig
    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: 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:
              status: 404
              code: NOT_FOUND
              message: Die angeforderte Ressource existiert nicht
    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: 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:
              status: 500
              code: INTERNAL_SERVER_ERROR
              message: Ein interner Serverfehler ist aufgetreten