Fluvigil Sources API

openapi: 3.2.0
info:
  title: Fluvigil Public Sources API
  version: 2.0.0
  license:
    name: Proprietary — use is governed by the terms of service
    url: https://fluvigil.de/terms
  description: 'Water levels and flood classifications of gauging stations in Germany and its neighbouring countries. Data sources: PEGELONLINE (WSV), Länderübergreifendes Hochwasserportal (LHP, CC BY 4.0 — attribution required) and the German state portals, plus the official hydrological services of Switzerland (BAFU), Austria (state services, eHYD), Czechia (ČHMÚ), Luxembourg (AGE), France (SIE / Hub''Eau), Denmark (Danmarks Miljøportal), the Netherlands (Rijkswaterstaat), Poland (IMGW-PIB) and Berlin (Wasserportal); weather by Deutscher Wetterdienst (via Bright Sky). Every station''s source and its attribution are listed on the site.

    Every provider attaches conditions to its data (credit line, licence, notices that the values are raw data or no official warning). A station whose provider is cleared for publication carries them as `sourceNotice` in the station list, the station detail, the river page, the neighbours and in every response that returns its values (readings, state, statistics, year-over-year, history context, analogue, forecast, report text, the flood situation and the routing simulation). Anyone passing these values on has to pass the notice on with them; the terms of service require every consumer of the API to show the notice with the values it displays. `form` says whether the provider allows a shortened notice (`textShort`) or only the full one (`full-only`, today Salzburg, which must never be shortened); `parts` names every source involved, the source of the values first. The text is German (the approved wording of the provider is never translated); the station detail also accepts `?locale=en` for the English labels around it.

    Changes in 2.0.0 (breaking): `GET /stations/timeline` is removed. Its replacement, `GET /stations/state-timeline`, replays the stored state history, answers with severity codes for station ids in column order and leaves out the coordinates, which `GET /stations/map` supplies. A client of the removed path switches to the new one and reads positions from the map list; calls to the old path now answer 404.

    Changes: `sourceNotice` is no longer limited to Salzburg. It is present for every source with a cleared licence, and its `id` is the key of the source record (for example `pegelonline`, `ch`, `niederoesterreich`) instead of always `salzburg`; a client that compares `id` with the literal `salzburg` to decide whether a notice exists has to test for `null` instead. The fields `sourceLine`, `rawData`, `disclaimer`, `noOfficialWarning` and `termsPath` are unchanged. An LHP gauge whose value cannot be attributed to the state portal that delivered it (not recorded yet) has no value until the next value sync; it keeps its flood class and the notice of the LHP.

    Anonymous access is allowed at free-tier limits (90-day readings range, 600 requests/hour per IP). An API key (created in the account area, sent as `X-Api-Key` or `Authorization: Bearer pm_...`) applies the limits of the account''s tier; exceeding the hourly budget returns 429.'
servers:
- url: /api/v1
security:
- {}
- apiKey: []
tags:
- name: Sources
paths:
  /sources/visible:
    get:
      summary: Station sources that are on
      operationId: getVisibleStationSources
      description: 'The station sources a visitor sees right now: those no licence hold, kill switch or operator switch has turned off. Answers `{ sources: string[] }` with the source keys in a fixed order; `/sources/stream` pushes the same list when it changes.'
      responses:
        '200':
          description: The visible source keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sources:
                    type: array
                    items:
                      type: string
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Sources
  /sources/stream:
    get:
      summary: Stream the station sources that are on
      operationId: streamVisibleStationSources
      description: 'A Server-Sent Events stream of the list `/sources/visible` answers. The event `sources` carries `{ sources: string[] }` and arrives on connect and whenever an operator switch changes the list; `ping` is a heartbeat every 25 seconds. The list is always sent whole, so there is nothing to resume. A stream counts as one request against the hourly budget; past 2,000 open streams the server answers 503 with `Retry-After`.'
      responses:
        '200':
          description: An open event stream.
          content:
            text/event-stream:
              schema:
                type: string
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Too many open streams; retry after the interval in `Retry-After`.
      tags:
      - Sources
components:
  responses:
    RateLimited:
      description: The hourly request budget for the tier is exhausted.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key