Matthias Jacob
190 lines
3.2 KiB
Markdown
190 lines
3.2 KiB
Markdown
# 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/](https://sachsen-pegel-proxy.vercel.app/)
|
|
- API docs: [https://sachsen-pegel-proxy.vercel.app/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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
npx vercel
|
|
npx vercel --prod
|
|
```
|
|
|
|
---
|
|
|
|
## 🏠 Home Assistant Example
|
|
|
|
```yaml
|
|
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
|