79 lines
2.6 KiB
Markdown
79 lines
2.6 KiB
Markdown
# Waste Collection API
|
|
|
|
FastAPI backend for German municipal waste collection schedules with Telegram notification support.
|
|
|
|
## ⚠️ Required Setup Step
|
|
|
|
The `waste_collection_schedule` library has a file `calendar.py` that conflicts with Python's stdlib `calendar` module. **You must rename it before running:**
|
|
|
|
```bash
|
|
mv waste_lib/custom_components/waste_collection_schedule/calendar.py \
|
|
waste_lib/custom_components/waste_collection_schedule/calendar_SKIPPED.py
|
|
```
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
# 1. Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# 2. Rename the conflicting calendar.py (see above)
|
|
|
|
# 3. Copy .env
|
|
cp .env.example .env
|
|
# Edit .env with your Telegram bot token and chat ID
|
|
|
|
# 4. Run
|
|
PYTHONPATH=. uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
waste_api/
|
|
├── app/
|
|
│ ├── main.py # FastAPI app + routes
|
|
│ ├── collector.py # waste_collection_schedule wrapper + icalevents bug fix
|
|
│ ├── schemas.py # Pydantic request/response models
|
|
│ ├── routes/
|
|
│ │ ├── sources.py # GET /sources, GET /sources/{id}
|
|
│ │ ├── collections.py # POST /collections/{ics,abfall_io,awm_muenchen_de}
|
|
│ │ └── notifications.py # POST/GET/DELETE /notifications
|
|
│ └── core/
|
|
│ ├── scheduler.py # Notification storage + due check
|
|
│ └── notifier.py # Telegram sender
|
|
├── SPEC.md # Full OpenAPI spec
|
|
└── requirements.txt
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| `GET` | `/health` | Health check |
|
|
| `GET` | `/sources` | List all source IDs |
|
|
| `GET` | `/sources/{id}` | Get params for a source |
|
|
| `POST` | `/collections/ics` | Fetch via generic ICS URL |
|
|
| `POST` | `/collections/abfall_io` | Fetch via Abfall.IO |
|
|
| `POST` | `/collections/awm_muenchen_de` | Fetch Munich waste schedule |
|
|
| `POST` | `/notifications` | Create notification rule |
|
|
| `GET` | `/notifications` | List all notification rules |
|
|
| `DELETE` | `/notifications/{id}` | Delete a rule |
|
|
|
|
## API Docs
|
|
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## Example: Munich
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/collections/awm_muenchen_de \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"street": "Bahnstr.", "house_number": "11", "count": 5}'
|
|
```
|
|
|
|
## Notifications
|
|
|
|
The scheduler runs via cron (not implemented yet) and fires Telegram messages when collections are due. Notifications are stored in `data/notifications.json`.
|