# 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