waste_api/SPEC.md

Waste Collection API — OpenAPI Specification

Base URL: http://localhost:8000
Version: 1.0.0
Purpose: Return waste collection schedules for German municipalities via push notification targets (email, Telegram, etc.)

---

API Endpoints

GET /health

Health check.

Response 200

{ "status": "ok" }

---

GET /sources

List all available source IDs (e.g. abfall_io, awm_muenchen_de, ics).

Response 200

{
  "count": 3,
  "sources": [
    { "id": "ics",           "name": "Generic ICS / iCal URL" },
    { "id": "abfall_io",     "name": "Abfall.IO (Germany)" },
    { "id": "awm_muenchen_de","name": "AWM München (Germany)" }
  ]
}

---

GET /sources/{source_id}

Describe required params for a given source.

Path params:
source_id — e.g. ics, abfall_io, awm_muenchen_de

Response 200

{
  "id": "abfall_io",
  "name": "Abfall.IO (Germany)",
  "params": [
    { "name": "key",        "type": "string",  "required": true,  "example": "8215c62763967916979e0e8566b6172e" },
    { "name": "f_id_kommune","type": "integer","required": true,  "example": 2999 },
    { "name": "f_id_strasse","type": "integer","required": true,  "example": 1087 }
  ]
}

---

POST /collections/ics

Fetch waste collections from a generic ICS/iCal URL.

Request body

{
  "url": "https://example.com/kalender.ics",
  "count": 10
}

Field	Type	Required	Default	Description
url	string	✅	—	Direct URL to .ics file
count	integer	❌	20	Max entries to return

Response 200

{
  "source": "ics",
  "url": "https://example.com/kalender.ics",
  "collections": [
    {
      "date": "2026-04-08",
      "type": "Restmülltonne",
      "daysUntil": 4,
      "icon": "mdi:trash-can"
    },
    {
      "date": "2026-04-27",
      "type": "Papiertonne",
      "daysUntil": 23,
      "icon": "mdi:paper-bin"
    }
  ]
}

---

POST /collections/abfall_io

Fetch collections via Abfall.IO (many German municipalities).

Request body

{
  "key": "8215c62763967916979e0e8566b6172e",
  "f_id_kommune": 2999,
  "f_id_strasse": 1087,
  "count": 20
}

Response 200 — same shape as /collections/ics with source: "abfall_io".

---

POST /collections/awm_muenchen_de

Fetch collections for Munich via AWM.

Request body

{
  "street": "Bahnstr.",
  "house_number": "11",
  "count": 20
}

Response 200 — same shape as /collections/ics with source: "awm_muenchen_de".

---

POST /notify

Queue a notification for a future collection.

Request body

{
  "source_id": "ics",
  "collection": {
    "date": "2026-04-08",
    "type": "Restmülltonne",
    "daysUntil": 4,
    "icon": "mdi:trash-can"
  },
  "notify_at_days_before": 1,
  "channels": ["telegram"],
  "chat_id": 1320170074
}

Field	Type	Required	Description
source_id	string	✅	Source that returned this collection
collection	object	✅	A single collection entry
notify_at_days_before	integer	❌	Days before collection to fire (default: 1)
channels	string[]	✅	["telegram"] (more coming)
chat_id	integer	✅	Telegram chat ID to notify

Response 200

{
  "ok": true,
  "notification_id": "notif_abc123",
  "message": "Reminder set for 2026-04-08: Restmülltonne"
}

---

GET /notifications

List all active notification rules.

Response 200

{
  "count": 1,
  "notifications": [
    {
      "id": "notif_abc123",
      "source_id": "ics",
      "collection_type": "Restmülltonne",
      "collection_date": "2026-04-08",
      "notify_at_days_before": 1,
      "channels": ["telegram"],
      "chat_id": 1320170074,
      "fired": false
    }
  ]
}

---

DELETE /notifications/{notification_id}

Delete a notification rule.

Response 200

{ "ok": true, "deleted": "notif_abc123" }

---

Error Responses

All endpoints return errors in this shape:

{
  "error": "Human-readable error message",
  "detail": "Optional technical detail"
}

Status	Meaning
400	Bad request — missing or invalid params
404	Source not found
422	Unprocessable entity — source returned no data
500	Internal server error

---

Data Models

Collection

{
  "date": "YYYY-MM-DD",
  "type": "Human-readable waste type string",
  "daysUntil": 4,
  "icon": "mdi:icon-name"
}

Notification

{
  "id": "notif_abc123",
  "source_id": "ics | abfall_io | awm_muenchen_de",
  "collection_type": "Restmülltonne",
  "collection_date": "2026-04-08",
  "notify_at_days_before": 1,
  "channels": ["telegram"],
  "chat_id": 1320170074,
  "fired": false
}