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:

mv waste_lib/custom_components/waste_collection_schedule/calendar.py \
   waste_lib/custom_components/waste_collection_schedule/calendar_SKIPPED.py

Setup

# 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

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.

2.6 KiB Raw Blame History