Fluvigil Me API

openapi: 3.2.0
info:
  title: Fluvigil Public Me 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: Me
paths:
  /me:
    get:
      summary: Confirm an API key
      operationId: getMe
      description: Confirms the API key sent with the request and reports the tier and limits it grants. Everywhere else on this API an unrecognised key is ignored and the request proceeds as anonymous on free-tier limits; this route rejects it instead, so a client can verify a key at setup time rather than silently running with less than it pays for.
      responses:
        '200':
          description: The key is valid. Returns its tier, the limits of that tier, and the owning organization id when the key belongs to a team.
        '401':
          description: No key was sent, or the key is unknown or revoked.
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Me
components:
  responses:
    RateLimited:
      description: The hourly request budget for the tier is exhausted.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key