From b5950b6ce1afa96c8041171d02d0481e26bb6872 Mon Sep 17 00:00:00 2001
From: Matthias Jacob <dev@matthiasjacob.net>
Date: Tue, 5 May 2026 03:22:39 +0200
Subject: [PATCH] Update README.md with detailed descriptions

---
 README.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 135 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4fd09ea..bcef44d 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,136 @@
-# sachsen_pegel_proxy
+# 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.
+
+---
+
+## ✨ 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-05-05T00:45:00+00:00",
+    "water_level_cm": 98,
+    "flow_m3s": 20.8,
+    "flood_alert_level": "Kein Hochwasser"
+  }
+}
+```
+
+---
+
+## 🚀 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/560021
+```
+
+API docs:
+
+```
+http://127.0.0.1:8000/docs
+```
+
+---
+
+## ☁️ Deploy (Vercel)
+
+```bash
+npx vercel
+npx vercel --prod
+```
+
+---
+
+## 🏠 Home Assistant Example
+
+```yaml
+rest:
+  - resource: "https://your-app.vercel.app/api/pegel/560021"
+    scan_interval: 300
+    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>
+```
+
+---
+
+## 📡 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