sachsen_pegel_proxy/README.md

Sachsen Pegel Proxy (HWIMS → JSON)

Small FastAPI service that converts the Sachsen HWIMS RSS feed into clean, machine-readable JSON.

Perfect for use with Home Assistant or other automation tools.

🌐 Live Service

• Running instance: https://sachsen-pegel-proxy.vercel.app/
• API docs: https://sachsen-pegel-proxy.vercel.app/docs

---

✨ Features

• Converts RSS → structured JSON

• Supports any Pegel ID

• Extracts:

  • water level (cm)
  • flow (m³/s)
  • flood alert level
  • timestamp (ISO format)

• Provides:

  • latest value
  • full history from feed

---

🔗 Example

Request:

GET /api/pegel/560021

Response:

{
  "station_id": "560021",
  "station_title": "Golzern 1 / Vereinigte Mulde",
  "latest": {
    "timestamp": "2026-01-01T12:00:00+00:00",
    "water_level_cm": 98,
    "flow_m3s": 20.8,
    "flood_alert_level": "Kein Hochwasser"
  }
}

Index request (all discovered stations):

GET /api/pegel

Index request with limit:

GET /api/pegel?limit=5

Index response shape:

{
  "count": 5,
  "total_available": 312,
  "items": [
    {
      "station_id": "560021",
      "station_title": "Golzern 1 / Vereinigte Mulde",
      "source": "https://www.umwelt.sachsen.de/umwelt/infosysteme/hwims/portal/web/feed/wasserstand-pegel-560021"
    }
  ],
  "source": "https://www.umwelt.sachsen.de/umwelt/infosysteme/hwims/portal/web/wasserstand-uebersicht",
  "fetched_at": "2026-05-05T01:00:00+00:00",
  "warnings": [
    "optional, only present for partial failures"
  ]
}

---

🚀 Local Development

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -r requirements.txt

uvicorn api.app:app --reload

Open:

http://127.0.0.1:8000/api/pegel
http://127.0.0.1:8000/api/pegel/560021

API docs:

http://127.0.0.1:8000/docs

---

☁️ Deploy (Vercel)

This repository does not include platform-specific deployment configuration. Deploy by connecting the repo in Vercel (or using the CLI), then verify the API endpoints after deployment.

npx vercel
npx vercel --prod

---

🏠 Home Assistant Example

rest:
  - resource: "https://your-app.vercel.app/api/pegel/560021"
    scan_interval: 300
    json_attributes_path: "$.latest"
    sensor:
      - name: "Pegel Wasserstand"
        value_template: "{{ value_json.latest.water_level_cm }}"
        unit_of_measurement: "cm"
        json_attributes:
          - flow_m3s
          - flood_alert_level

---

⚙️ Configuration

No config required.

Pegel ID is passed via URL:

/api/pegel/<id>

Index endpoint:

/api/pegel

Query params for index:

• limit (positive integer, optional; invalid values return HTTP 400)

---

📡 Data Source

Data provided by the official Sachsen environmental portal:

https://www.umwelt.sachsen.de/

Example feed:

https://www.umwelt.sachsen.de/umwelt/infosysteme/hwims/portal/web/feed/wasserstand-pegel-560021

---

⚠️ Disclaimer

• No guarantees on data accuracy or availability
• Feed format may change
• Not affiliated with the State of Saxony

---

📝 License

MIT