# InfraNode API | Vollständige Endpunkt-Referenz

> Volltext aller Endpunkte der InfraNode API in einem Dokument. Normalisierte Open-Data-Proxy-API für deutsche Großstädte (84 Städte, 28 Kern-Städte voll abgedeckt; Stammdaten, Luftqualität, Wetter, POIs, ÖPNV, Verkehr). Kanonischer Envelope mit data und meta auf Top-Level (source_status, correlation_id und cache_status in meta); jeder data-Record trägt zusätzlich ein attribution-Feld mit Lizenz und Herkunft.

# Live

## GET /api/v1/live/{slug}/air

**Live-Alias für Luftqualität OpenAQ**

Spiegelt den bestehenden OpenAQ-Luft-Endpunkt unter der Live-Kategorie. Gleicher Envelope-Kontrakt wie /api/v1/cities/{slug}/air, derselbe Handler. Der alte Pfad bleibt als Alias erhalten und ist als veraltet markiert (Deprecation-Header und deprecated=true).

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/air"
```

## GET /api/v1/live/{slug}/air-uba

**Live-Alias für Luftqualität UBA**

Spiegelt den bestehenden UBA-Luft-Endpunkt unter der Live-Kategorie. Gleicher Envelope-Kontrakt wie /api/v1/cities/{slug}/air-uba, derselbe Handler. Der alte Pfad bleibt als Alias erhalten und ist als veraltet markiert.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/air-uba"
```

## GET /api/v1/live/{city}/baustellen

**Live-Baustellen je Stadt (Mobilithek DATEX-II)**

Liefert die Baustellen einer Stadt aus der Mobilithek (DATEX-II SituationPublication) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Parameter

- `city` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/example/baustellen"
```

## GET /api/v1/live/berlin/verkehrsmeldungen

**Live-Verkehrsmeldungen Berlin (Mobilithek DATEX-II)**

Liefert die Berlin-Verkehrsmeldungen (SenMVKU, DATEX-II SituationPublication) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/berlin/verkehrsmeldungen"
```

## GET /api/v1/live/dortmund/parking

**Live-Parkbelegung Dortmund (Mobilithek DATEX-II)**

Liefert die Dortmund-Parkbelegung (dynamisches Parkleitsystem, DATEX-II ParkingStatusPublication) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/dortmund/parking"
```

## GET /api/v1/live/{city}/ereignisse

**Live-Verkehrsereignisse je Stadt (Mobilithek DATEX-II)**

Liefert die Verkehrsereignisse einer Stadt aus der Mobilithek (DATEX-II SituationPublication) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Parameter

- `city` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/example/ereignisse"
```

## GET /api/v1/live/eround/charging

**Live-Ladesäulen-Belegung eRound (Mobilithek DATEX-II V3)**

Liefert die eRound-Ladesäulen-Belegung (AFIR-Recharging, DATEX-II V3 EnergyInfrastructureStatusPublication, JSON-Syntax) im Live-Envelope. Bislang die einzige V3-Quelle; sie liefert die Echtzeit-Belegung der Ladesäulen. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Lizenz Creative Commons CC Zero (Tier A). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/eround/charging"
```

## GET /api/v1/live/{slug}/flood

**Live-Alias für Hochwasser-Warnstufen LHP**

Spiegelt den bestehenden LHP-Hochwasser-Endpunkt unter der Live-Kategorie. Gleicher Envelope-Kontrakt wie /api/v1/cities/{slug}/flood, derselbe Handler. Der alte Pfad bleibt als Alias erhalten und ist als veraltet markiert.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/flood"
```

## GET /api/v1/live/hamburg/departures

**Live-ÖPNV-Abfahrten Hamburg je Station (HVV-Geofox-GTI)**

Liefert die Echtzeit-Abfahrtstafel einer HVV-Station aus der HVV-Geofox-GTI-API: je Abfahrt Linie, Richtung, Soll-Offset in Minuten, Verspätung in Sekunden und Linien-Störungshinweise. Stadt fix hamburg (Geofox deckt nur den HVV-Raum ab). Der Query-Parameter station ist ein Stationsname (Default Hauptbahnhof), der intern via checkName auf die Geofox-Station-ID aufgelöst wird. Der meta-Block trägt zusätzlich as_of und refresh_seconds (60). Tier C live-only: die Geofox-Lizenz ist nicht offen (source_status der Quelle = unknown), reine Live-Daten, nur kurzlebig im Redis-Cache gehalten. Toggle aus oder fehlende Credentials -> 200 source_status="disabled"; unbekannte Station oder keine Abfahrten -> 200 source_status="no_data"; toter Upstream ohne Cache -> 503 mit Hint.

### Parameter

- `station` (query, string, optional) , HVV-Stationsname (Default "Hamburg Hauptbahnhof").

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/departures"
```

## GET /api/v1/live/kiel/zaehlstellen

**Live-Zähldaten Kiel, Kfz- und Radzählstellen (Mobilithek DATEX-II)**

Liefert die Kiel-Zähldaten (Kfz-Dauerzählstellen und Radzähler, DATEX-II MeasuredDataPublication) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/kiel/zaehlstellen"
```

## GET /api/v1/live/koeln/umweltzone

**Live-Umweltzone Köln (Mobilithek DATEX-II)**

Liefert die Köln-Umweltzone (LowEmissionZone, MoCKiii, DATEX-II SituationPublication) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data". Reine Live-Daten, nur im Redis-Cache gehalten.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/koeln/umweltzone"
```

## GET /api/v1/live/{slug}/traffic

**Live-Alias für Verkehr und Baustellen Autobahn**

Spiegelt den bestehenden Autobahn-Verkehrs-Endpunkt unter der Live-Kategorie. Gleicher Envelope-Kontrakt wie /api/v1/cities/{slug}/traffic, derselbe Handler. Der alte Pfad bleibt als Alias erhalten und ist als veraltet markiert.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/traffic"
```

## GET /api/v1/live/{city}/traffic-flow

**Live-Verkehrslage je Stadt (Mobilithek DATEX-II)**

Liefert die minutenfrische Verkehrslage einer Stadt aus der Mobilithek (DATEX-II) im Live-Envelope. Der meta-Block trägt zusätzlich as_of (Datenstand) und refresh_seconds (Aktualisierungstakt). Solange Zertifikat und Abo noch nicht gesetzt sind -> 200 source_status="disabled" (nie 5xx); kein Datenpaket -> 200 source_status="no_data".

### Parameter

- `city` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/example/traffic-flow"
```

## GET /api/v1/live/{city}/transit/departures

**Live-ÖPNV-Abfahrten je Halt mit Verspätung (GTFS-RT, Tier B)**

Liefert die Live-Abfahrten eines Halts mit aktueller Verspätung aus dem GTFS-RT-Feed (gtfs.de bzw. Mobilithek-DELFI, CC-BY-SA = Tier B) im Live-Envelope (meta mit as_of und refresh_seconds=45, dem Poller-Takt). Der Request-Pfad liest NUR aus Redis: ein Hintergrund-Poller parst den Feed einmal je Takt, sodass nicht bei jedem Request ein 68-MB-Feed geparst wird. Toggle aus -> 200 source_status="disabled"; kein Update in Redis -> 200 source_status="no_data"; ungültige stop_id -> 400. Reine Live-Daten, nur im Redis-Cache gehalten (Tier B).

### Parameter

- `city` (path, string, Pflicht)
- `stop_id` (query, string, Pflicht) , DELFI-Halt-ID im Muster de:<AGS>:<id> (gegen eine Allowlist geprüft).

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/example/transit/departures?stop_id=example"
```

## GET /api/v1/live/{city}/transit/routes/{route_id}/status

**Live-ÖPNV-Verspätungslage einer Linie (GTFS-RT, Tier B)**

Aggregiert die aktiven Fahrten einer Linie aus dem GTFS-RT-Feed (Tier B): active_trips (Anzahl), avg_delay_s und max_delay_s, im Live-Envelope (refresh_seconds=45). Der Request-Pfad liest NUR aus Redis. Toggle aus -> disabled; keine aktiven Fahrten -> no_data. Reine Live-Daten, nur im Redis-Cache gehalten (Tier B).

### Parameter

- `city` (path, string, Pflicht)
- `route_id` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/example/transit/routes/example/status"
```

## GET /api/v1/live/{city}/transit/trips/{trip_id}

**Live-ÖPNV-Fahrt-Detail inkl. geschätzter Position (GTFS-RT, Tier B)**

Liefert das Fahrt-Detail (Verspätung, Halt-Updates) inklusive linear interpolierter Position (als estimated=true gekennzeichnet) aus dem GTFS-RT-Feed (Tier B) im Live-Envelope (refresh_seconds=45). Der Request-Pfad liest NUR aus Redis. Lässt sich die Fahrt nicht gegen das statische GTFS auflösen, trägt der Payload unresolved=true (ehrlich statt 500). Toggle aus -> disabled; kein Update -> no_data. Reine Live-Daten, nur im Redis-Cache gehalten (Tier B).

### Parameter

- `city` (path, string, Pflicht)
- `trip_id` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/example/transit/trips/example"
```

## GET /api/v1/live/{slug}/water-level

**Live-Alias für Pegelstand PEGELONLINE**

Spiegelt den bestehenden PEGELONLINE-Endpunkt unter der Live-Kategorie. Gleicher Envelope-Kontrakt wie /api/v1/cities/{slug}/water-level, derselbe Handler. Der alte Pfad bleibt als Alias erhalten und ist als veraltet markiert.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/water-level"
```

## GET /api/v1/live/{slug}/webcams

**Live-Alias für Autobahn-Webcams**

Spiegelt den bestehenden Autobahn-Webcam-Endpunkt unter der Live-Kategorie. Gleicher Envelope-Kontrakt wie /api/v1/cities/{slug}/webcams, derselbe Handler. Der alte Pfad bleibt als Alias erhalten und ist als veraltet markiert.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/live/hamburg/webcams"
```

# cities

## GET /api/v1/cities

**Alle bekannten Städte auflisten**

Listet die Einträge des Stadt-Registers: 84 deutsche Großstädte über 100.000 Einwohner, davon 28 Kern-Städte mit voller Quellen-Abdeckung. Jeder Eintrag trägt den Slug, den du als {slug}-Pfadparameter in allen weiteren Endpunkten verwendest.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities"
```

## GET /api/v1/cities/{slug}

**Eine Stadt aus dem Register holen**

Liefert den Register-Eintrag zur Stadt mit dem angegebenen {slug}. Ein unbekannter Slug löst den 404-Fehler-Envelope aus, dessen Hint auf die Stadt-Liste verweist.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg"
```

## GET /api/v1/cities/{slug}/air

**Luftqualität je Stadt (OpenAQ)**

Aktuelle Luftqualitäts-Messwerte einer Stadt aus OpenAQ im kanonischen Envelope. Die Schadstoff-Messwerte stehen in data, Quelle und source_status in meta. Werte sind live (kein Zwischenbestand). Sonderfälle: deaktivierte Quelle liefert 200 mit data=null und source_status="disabled"; toter Upstream ohne Cache liefert 503 mit Hint auf GET /api/v1/health.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/air"
```

## GET /api/v1/cities/{slug}/air-uba

**Luftqualität je Stadt (Umweltbundesamt)**

Luftqualitäts-Messwerte einer Stadt aus der Luftdaten-API des Umweltbundesamts im kanonischen Envelope. Amtlicher Pfad, klar getrennt vom OpenAQ-Endpunkt (/air): wähle diesen für behördlich validierte Werte. Sonderfälle: deaktivierte Quelle liefert 200 mit source_status="disabled"; toter Upstream ohne Cache liefert 503 mit Hint auf GET /api/v1/health.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/air-uba"
```

## GET /api/v1/cities/{slug}/base

**Stadt-Stammdaten aus Wikidata**

Liefert Einwohnerzahl, Fläche und Geo-Koordinaten einer Stadt aus Wikidata im kanonischen Envelope mit Attribution und Lizenz-Tag. Ist die Quelle deaktiviert, antwortet die Route mit 200, data=null und meta.source_status="disabled" (nie 5xx). Ist der Upstream tot und liegt kein zwischengespeicherter Wert vor, kommt 503 mit einem Hint auf GET /api/v1/health.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/base"
```

## GET /api/v1/cities/{slug}/charging

**E-Ladesäulen-Standorte je Stadt (BNetzA, Tier A)**

Liefert die E-Ladesäulen-Standorte einer Stadt (nur Stammdaten, KEINE Belegung) aus dem BNetzA-Ladesäulenregister im kanonischen Envelope. Die Daten stammen aus dem CSV-Bulk-Download der BNetzA (data.bundesnetzagentur.de) und werden periodisch aktualisiert; die Route liefert den jüngsten aufbereiteten Stand, keinen Live-Abruf. Deaktiviert -> 200 source_status="disabled"; kein Snapshot -> 200 source_status="not_ingested".

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/charging"
```

## GET /api/v1/cities/{slug}/demographics

**Demografie-Zeitreihen je Stadt (GENESIS/Regionalstatistik, Tier A)**

Liefert Demografie-Stammwerte und Zeitreihen einer Stadt aus der POST-API der GENESIS-/Regionalstatistik im kanonischen Envelope. Der Zugang ist account-gebunden: ohne hinterlegte Zugangsdaten oder bei deaktivierter Quelle antwortet der Endpunkt mit 200 source_status="disabled". Tier A. Toter Upstream ohne Cache -> 503 mit Hint.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/demographics"
```

## GET /api/v1/cities/{slug}/election

**Wahlergebnis je Stadt (Bundeswahlleiterin, Tier A)**

Liefert das Wahlergebnis je Wahlkreis/Kreis einer Stadt aus dem offline aufbereiteten Bundeswahl-Snapshot im kanonischen Envelope. Die Granularität wird ehrlich als "teilweise" ausgewiesen. Deaktiviert -> 200 source_status="disabled". Batch noch nicht gelaufen -> 200 source_status="not_ingested".

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/election"
```

## GET /api/v1/cities/{slug}/energy

**Energie-Anlagen je Stadt (MaStR, Tier A)**

Liefert die Energie-Anlagen (PV/Wind/Speicher/Biogas) einer Stadt aus dem offline aufbereiteten MaStR-SQLite-Store im kanonischen Envelope. Kein Upstream im Request-Pfad, der Abruf liest nur den vorbereiteten Bestand. Deaktiviert -> 200 source_status="disabled". Batch noch nicht gelaufen -> 200 source_status="not_ingested" (nie 5xx).

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/energy"
```

## GET /api/v1/cities/{slug}/events

**Veranstaltungen je Stadt (destination.one)**

Aktuelle und kommende Veranstaltungen einer Stadt aus der account-gebundenen Quelle destination.one/eT4.META im kanonischen Envelope. Die Lizenz wird je Datensatz aus dem Lizenzfeld abgeleitet (CC0/CC-BY, CC-BY-SA, sonst unbekannt) und in attribution gespiegelt. Vergangene Termine werden herausgefiltert. Sonderfälle: ist die Quelle aus oder fehlt der licensekey, kommt 200 mit source_status="disabled"; liefert die Quelle nichts Aktuelles, kommt 200 mit source_status="no_data"; toter Upstream ohne Cache liefert 503 mit Hint.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/events"
```

## GET /api/v1/cities/{slug}/flood

**Hochwasser-Warnstufen je Stadt (LHP, Tier A)**

Liefert die aktuellen Hochwasser-Warnstufen der kuratierten Pegel einer Stadt aus dem Länderübergreifenden Hochwasserportal (LHP) im kanonischen Envelope. Die Attribution trägt den "Stand:"-Zeitstempel (Pflicht). Tier A. Teilabdeckung (kuratierte Pegel je Stadt): nur berlin, bonn, dresden, duesseldorf, duisburg, erfurt, essen, frankfurt-am-main, hamburg, koeln, leipzig, mainz, muenchen, nuernberg liefern Daten. Andere registrierte Städte antworten ehrlich mit 200 source_status="not_covered", data=null und meta.covered_cities (Liste der abgedeckten Städte). Weitere Sonderfälle: deaktiviert -> 200 source_status="disabled"; toter Upstream ohne Cache -> 503 mit Hint.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/flood"
```

## GET /api/v1/cities/{slug}/geo

**Verwaltungsgrenze je Stadt (BKG VG250, Tier A)**

Liefert die Attributdaten der Verwaltungsgrenze (AGS, Gemeindename, Fläche) einer Stadt aus dem offline aufbereiteten BKG-VG250-Snapshot im kanonischen Envelope. Attribution wortgenau "(c) GeoBasis-DE / BKG". Deaktiviert -> 200 source_status="disabled". Snapshot noch nicht gebaut -> 200 source_status="not_ingested".

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/geo"
```

## GET /api/v1/cities/{slug}/health

**Krankenhaus-Stammdaten je Stadt (Destatis-Verzeichnis, Tier A)**

Liefert die Krankenhaus-Stammdaten einer Stadt aus dem Destatis-Krankenhausverzeichnis (über GENESIS) im kanonischen Envelope. Die Attribution trägt den exakten Destatis-Wortlaut (nicht pauschal DL-DE/BY). Tier A. Deaktiviert -> 200 source_status="disabled". Toter Upstream ohne Cache -> 503 mit Hint.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/health"
```

## GET /api/v1/cities/{slug}/holidays

**Feiertage und Schulferien je Stadt (Seed, gemeinfrei)**

Liefert Feiertage und Schulferien je Bundesland (über entry.state aufgelöst) aus den eingebetteten Seed-Daten (data/seeds/) im kanonischen Envelope. Kein Upstream, gemeinfrei. Deaktiviert -> 200 source_status="disabled". Kein Seed für das Bundesland -> 200 source_status="no_data".

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/holidays"
```

## GET /api/v1/cities/{slug}/icu-live

**Intensivbetten-Belegung live je Stadt (DIVI, Tier C)**

Liefert die klinikscharfe Intensivbetten-Belegung im Kreis einer Stadt aus dem DIVI-Intensivregister (RKI) im kanonischen Envelope. Tier C, nur live (Datenbank-Schutzrecht, kein Zwischenbestand). Deaktiviert -> 200 source_status="disabled". Toter Upstream ohne Cache -> 503 mit Hint.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/icu-live"
```

## GET /api/v1/cities/{slug}/pois

**POIs je Stadt, nach Typ gefiltert (OSM/Overpass, Tier B)**

Liefert POIs einer Stadt aus OpenStreetMap (über Overpass) im kanonischen Envelope, gefiltert nach dem Query-Parameter type. Der Typ wird gegen eine feste Liste geprüft; ein unbekannter Typ löst 422 aus (kein roher Input in die Overpass-Query). Tier B (copyleft). Deaktiviert -> 200 source_status="disabled".

### Parameter

- `slug` (path, string, Pflicht)
- `type` (query, string, Pflicht) , POI-Typ aus der erlaubten Liste (z.B. hospital, school, pharmacy).

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/pois?type=example"
```

## GET /api/v1/cities/{slug}/pollen-uv

**Pollenflug und UV-Index je Stadt (DWD opendata, Tier A)**

Liefert Pollenflug-Gefahrenindex und UV-Index für die Großregion einer Stadt aus DWD opendata im kanonischen Envelope. Die Daten sind nach DWD-Großregionen gegliedert, NICHT stadtgenau (region_name im Payload). Attribution mit modified=true (GeoNutzV). Tier A. Deaktiviert -> 200 source_status="disabled".

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/pollen-uv"
```

## GET /api/v1/cities/{slug}/road-events

**Innerstädtische Baustellen und Sperrungen je Stadt (Tier A)**

Liefert innerstädtische Baustellen und Sperrungen einer Stadt aus den schlüssellosen Pro-Stadt-Quellen (Berlin VIZ, Hamburg, Köln, München, MobiData BW) im kanonischen Envelope. Teilabdeckung (kuratierte Connectoren): nur berlin, hamburg, koeln, muenchen, stuttgart liefern Daten. Eine Stadt ohne Connector antwortet ehrlich mit 200 source_status="not_covered", data=null und meta.covered_cities (Liste der abgedeckten Städte), klar unterscheidbar von no_data (Connector vorhanden, aber gerade keine Ereignisse). Tier A. Deaktiviert -> 200 source_status="disabled". Toter Upstream ohne Cache -> 503 mit Hint.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/road-events"
```

## GET /api/v1/cities/{slug}/traffic

**Baustellen und Verkehrsmeldungen je Stadt (Autobahn-API)**

Baustellen (roadworks) und Verkehrswarnungen (warnings) im Umfeld einer Stadt aus der Autobahn-API im kanonischen Envelope. Die Meldungen werden per Bounding-Box um die Stadt-Koordinaten gefiltert, data enthält die passenden Einträge. Teilabdeckung (kuratierte Autobahnen je Stadt): nur berlin, hamburg, koeln, muenchen liefern Daten. Andere registrierte Städte antworten ehrlich mit 200 source_status="not_covered", data=null und meta.covered_cities (Liste der abgedeckten Städte), klar unterscheidbar von no_data (abgedeckt, aber gerade keine Meldung). Weitere Sonderfälle: deaktivierte Quelle liefert 200 mit source_status="disabled"; toter Upstream ohne Cache liefert 503 mit Hint auf GET /api/v1/health.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/traffic"
```

## GET /api/v1/cities/{slug}/transit

**ÖPNV-Haltestellen je Stadt (DELFI und HVV GTFS)**

Normalisierte ÖPNV-Haltestellen einer Stadt aus dem bundesweiten DELFI-GTFS-Feed bzw. dem HVV-Feed im kanonischen Envelope. Die Daten werden offline aufbereitet und als Snapshot je Stadt gehalten, sodass der Abruf schnell antwortet, ohne den Feed pro Request zu parsen. Sonderfälle: sind beide Quellen deaktiviert, kommt 200 mit source_status="disabled"; liegt noch kein Snapshot vor, kommt 200 mit source_status="not_ingested" und leeren data, nie ein 5xx.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/transit"
```

## GET /api/v1/cities/{slug}/water-level

**Pegelstand je Stadt (PEGELONLINE, Tier A, Teilabdeckung)**

Liefert den aktuellen Pegelstand der nächstgelegenen Station einer Stadt aus PEGELONLINE im kanonischen Envelope. Teilabdeckung: nur Städte an Bundeswasserstraßen haben eine Station, sonst kommt 200 mit source_status="no_data" (kein 5xx). Tier A. Deaktiviert -> 200 source_status="disabled".

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/water-level"
```

## GET /api/v1/cities/{slug}/weather

**Wetter je Stadt (DWD über Bright Sky)**

Aktuelle Wetter-Messwerte einer Stadt vom Deutschen Wetterdienst (über Bright Sky) im kanonischen Envelope. data trägt die Messwerte, attribution den GeoNutzV-Bearbeitungshinweis (modified=true). Sonderfälle: deaktivierte Quelle liefert 200 mit source_status="disabled"; toter Upstream ohne Cache liefert 503 mit Hint auf GET /api/v1/health.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/weather"
```

## GET /api/v1/cities/{slug}/webcams

**Autobahn-Webcams je Stadt (Autobahn-API, Tier A)**

Liefert Autobahn-Webcams (Koordinaten und Bild-URLs) im Umfeld einer Stadt aus dem schlüssellosen Autobahn-Webcam-Service. Die Webcams werden per Bounding-Box um die Stadt gefiltert. Tier A. Teilabdeckung (kuratierte Autobahnen je Stadt): nur berlin, hamburg, koeln, muenchen liefern Daten. Andere registrierte Städte antworten ehrlich mit 200 source_status="not_covered", data=null und meta.covered_cities (Liste der abgedeckten Städte), klar unterscheidbar von no_data (abgedeckt, aber gerade keine Webcam). Weitere Sonderfälle: deaktiviert -> 200 source_status="disabled"; toter Upstream ohne Cache -> 503 mit Hint. Hinweis: Die Autobahn-Webcam-Quelle liefert aktuell bundesweit keine Webcams, daher antwortet der Endpunkt derzeit durchgehend mit no_data.

### Parameter

- `slug` (path, string, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/cities/hamburg/webcams"
```

# compare

## GET /api/v1/compare

**Eine Ressource über mehrere Städte vergleichen**

Vergleicht EINE Ressource (resource) über mehrere Städte (cities, kommasepariert) in einer einzigen Antwort. Jede Stadt trägt einen eigenen source_status (ok/disabled/no_data/error/not_found); eine fehlende oder tote Stadt-Quelle führt nicht zu einem Gesamt-5xx, sondern wird pro Stadt ehrlich ausgewiesen. resource wird gegen eine feste Liste geprüft (unbekannt -> 400). Das Ergebnis ist paginierbar (page/limit/offset/sort).

### Parameter

- `cities` (query, string, Pflicht) , Kommaseparierte Stadt-Slugs (auf MAX_CITIES begrenzt).
- `resource` (query, string, Pflicht) , Zu vergleichende Ressource (aus der festen Liste); unbekannt -> 400 invalid_request.
- `page` (query, integer, optional)
- `limit` (query, integer, optional)
- `offset` (query, integer, optional)
- `sort` (query, string, optional)
- `order` (query, string, optional)
- `If-None-Match` (header, string, optional) , Conditional GET; If-None-Match == ETag -> 304 Not Modified ohne Body.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/compare?cities=berlin%2Ckoeln%2Chamburg&resource=weather"
```

# meta

## GET /api/v1/_boom

**Erzwungener Upstream-Fehler (Demo)**

Existiert nur zum Testen des zentralen Fehler-Mappings. Liefert immer einen 503-Fehler-Envelope.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/_boom"
```

## GET /api/v1/echo

**Integer-Query zurückgeben (Validierungs-Demo)**

Gibt den übergebenen Integer-Query-Parameter zurück. Ein nicht-ganzzahliger Wert löst den einheitlichen 400-Fehler-Envelope aus und zeigt so die Eingabevalidierung.

### Parameter

- `n` (query, integer, Pflicht)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/echo?n=1"
```

## GET /api/v1/health

**Liveness und Readiness der App prüfen**

Liefert den App-Status und die Redis-Erreichbarkeit. Gedacht für Uptime-Monitore und Load-Balancer-Probes: antwortet mit 200, sobald die App bereit ist, sonst mit einem Fehlerstatus.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/health"
```

## GET /api/v1/openapi.yaml

**Diese OpenAPI-Spec als YAML**

Liefert die handgepflegte Spec als application/yaml. FastAPI serviert intern nur /openapi.json; diese Route stellt die stabile YAML-Variante bereit.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/openapi.yaml"
```

## GET /api/v1/ping

**Einfacher Ping mit Correlation-ID**

Gibt eine Pong-Antwort inklusive correlation_id zurück und schreibt eine strukturierte JSON-Log-Zeile mit request_id. Nützlich, um die Request-Verkettung im Logging zu prüfen.

### Beispiel

```bash
curl "https://infranode.dev/api/v1/ping"
```

## GET /api/v1/sources

**Status aller Upstream-Quellen**

Listet je bekannter Quelle den enabled-Zustand (aus den Settings) und den Circuit-Breaker-Zustand (CLOSED/OPEN/HALF_OPEN). So ist auf einen Blick sichtbar, welche Quelle gerade liefert und welche pausiert ist.

### Parameter

- `If-None-Match` (header, string, optional) , Conditional GET. Stimmt der Wert mit dem aktuellen ETag überein, antwortet der Server mit 304 Not Modified ohne Body.
- `page` (query, integer, optional)
- `limit` (query, integer, optional) , Seitengröße. Wird auf MAX_LIMIT (200) gedeckelt: zu große Werte liefern eine 200er-Seite mit 200 Einträgen statt eines Fehlers.
- `offset` (query, integer, optional) , Ein zu großer Offset liefert eine leere Seite (200), nie 500.
- `sort` (query, string, optional) , Nur die gelisteten Felder sind erlaubt; ein unbekanntes Feld wird mit 400 (invalid_request) abgewiesen, bevor es ausgewertet wird.
- `order` (query, string, optional)

### Beispiel

```bash
curl "https://infranode.dev/api/v1/sources"
```