Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: InfraNode Compare API
version: 1.0.0
description: 'Open-Source-Proxy-REST-API für normalisierte offene Daten deutscher Großstädte. Bekannt sind 84 Städte über 100.000 Einwohner, davon 28 Kern-Städte mit voller Quellen-Abdeckung; weitere Städte werden über AGS- und geobasierte Quellen bedient. Jede Antwort folgt demselben kanonischen Envelope (data/meta/attribution) mit Lizenz-Tag und ehrlichem source_status (ok/no_data/disabled/not_covered). Teilabgedeckte Endpunkte (flood, traffic, road-events) liefern für eine nicht-abgedeckte Stadt 200 source_status="not_covered" + meta.covered_cities statt eines leeren "ok"; die Abdeckung listet die Seite /abdeckung. Pfade tragen den vollen /api/v1-Prefix, damit die ausgelieferte Spec driftfrei zu den live registrierten Routen bleibt. Paginierung ist kanal-abhängig: direktes REST liefert Datenart-Listen voll, GPT-Actions und MCP sind serverseitig bzw. client-seitig auf ein Default-Limit gebunden; limit=all (bzw. ?all=1) erzwingt kanalunabhängig die Vollausgabe. Details siehe meta.pagination (Meta-Schema). Der Stadt-Slug im Pfad wird tolerant aufgelöst: der deutsche Name mit oder ohne Umlaute, beliebige Groß/Kleinschreibung, gängige englische Exonyme und Kurzformen führen zum kanonischen Slug (München/münchen/munich/munchen -> muenchen, cologne -> koeln, frankfurt -> frankfurt-am-main). Ein unbekannter Name liefert 404 mit einem "Meintest du ...?"-Hinweis auf den nächstliegenden Slug; die kanonischen Slugs listet GET /api/v1/cities. Feldnamen-Konvention (seit 2026-07-25 vereinheitlicht): Felder heissen durchgaengig snake_case und englisch. Gleiche Konzepte tragen ueberall denselben Namen: post_code (immer fuenfstelliger String, fuehrende Null bleibt erhalten), street, house_number, place, name, start, end, distance_km, power_kw, lat/lon. Fehlt eine Angabe in der Quelle, ist das Feld null statt Leerstring. Zeitstempel tragen immer eine Zeitzone. Uebergangsweise stehen die frueheren Namen (plz, zip, strasse, hausnummer, ort, city, bezeichnung, beginn, ende, art, dist_km, leistung_kw, einheit_typ sowie die camelCase-Rohfelder des Autobahn-Feeds) mit identischem Wert daneben; sie sind ABGEKUENDIGT und werden fruehestens 30 Tage nach der Ankuendigung im Changelog entfernt.'
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://infranode.dev
description: Öffentliche gehostete API, keylos (Standard)
- url: http://localhost
description: Lokaler Caddy-Ingress (Docker Compose)
tags:
- name: compare
description: Multi-City-Vergleich einer Ressource über mehrere Städte
paths:
/api/v1/compare:
get:
tags:
- compare
summary: Eine Ressource über mehrere Städte vergleichen
x-summary-en: Compare one resource across multiple cities
description: 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). Neben weather/air sind auch indicators, demographics, unemployment, tourism, charging-status und weather-warnings vergleichbar. Das Ergebnis ist paginierbar (page/limit/offset/sort).
x-description-en: Compares ONE resource across multiple cities (comma-separated) in a single response. Each city carries its own source_status (ok/disabled/no_data/error/not_found); a missing or dead city source does not cause an overall 5xx but is reported honestly per city. resource is checked against a fixed list (unknown -> 400). Besides weather/air, indicators, demographics, unemployment, tourism, charging-status and weather-warnings can be compared as well. The result is paginated (page/limit/offset/sort).
operationId: compareCities
parameters:
- in: query
name: cities
required: true
schema:
type: string
example: berlin,koeln,hamburg
description: Kommaseparierte Stadt-Slugs (auf MAX_CITIES begrenzt).
x-description-en: Comma-separated city slugs (limited to MAX_CITIES).
- in: query
name: resource
required: true
schema:
type: string
enum:
- weather
- air
- indicators
- demographics
- unemployment
- tourism
- charging-status
- weather-warnings
description: Zu vergleichende Ressource; unbekannt -> 400 invalid_request. weather/air = Live-Adapter (DWD/UBA); indicators, demographics, unemployment, tourism, charging-status und weather-warnings delegieren an die jeweiligen Stadt-Endpunkte (identisches Verhalten inkl. Attribution). charging-status liefert im Compare nur die Aggregate (points_omitted statt Einzelpunkt-Liste).
x-description-en: Resource to compare; unknown -> 400 invalid_request. weather/air = live adapters (DWD/UBA); indicators, demographics, unemployment, tourism, charging-status and weather-warnings delegate to the per-city endpoints (identical behaviour incl. attribution). charging-status returns aggregates only in compare (points_omitted instead of the point list).
- in: query
name: page
schema:
type: integer
minimum: 1
default: 1
- in: query
name: limit
schema:
type: integer
minimum: 1
default: 50
- in: query
name: offset
schema:
type: integer
minimum: 0
default: 0
- in: query
name: sort
schema:
type: string
enum:
- city
- source_status
- in: query
name: order
schema:
type: string
enum:
- asc
- desc
default: asc
- in: header
name: If-None-Match
required: false
schema:
type: string
description: Conditional GET; If-None-Match == ETag -> 304 Not Modified ohne Body.
x-description-en: Conditional GET; If-None-Match == ETag -> 304 Not Modified with no body.
responses:
'200':
description: Vergleichsliste mit per-Stadt source_status
headers:
ETag:
$ref: '#/components/headers/ETag'
Cache-Control:
$ref: '#/components/headers/CacheControl'
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
type: object
required:
- city
- source_status
properties:
city:
type: string
data:
type: object
nullable: true
source_status:
type: string
enum:
- ok
- disabled
- no_data
- error
- not_found
meta:
$ref: '#/components/schemas/Meta'
'304':
$ref: '#/components/responses/NotModified'
'400':
description: Unbekannte resource oder leeres cities (invalid_request)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
ErrorDetail:
type: object
required:
- code
- message
properties:
code:
type: string
example: upstream_unavailable
message:
type: string
example: Simulated upstream failure
hint:
type: string
nullable: true
Meta:
type: object
properties:
correlation_id:
type: string
nullable: true
source_status:
type: string
description: Ehrlicher Quellen-Status der Antwort. "ok" (Daten vorhanden), "no_data" (Quelle erreichbar/abgedeckt, aber gerade keine Daten), "disabled" (Quelle per Toggle aus), "not_ingested" (kein Snapshot), "not_covered" (Stadt ist für diesen teilabgedeckten Endpunkt strukturell nicht abgedeckt; data=null, siehe covered_cities). Klar unterscheidbar vom 404 (Stadt unbekannt).
enum:
- ok
- no_data
- disabled
- not_ingested
- not_covered
cache_status:
type: string
nullable: true
description: Cache-Herkunft (hit/miss/stale), sofern die Route cacht.
covered_cities:
type: array
items:
type: string
description: 'Nur bei source_status="not_covered": die Stadt-Slugs, die dieser teilabgedeckte Endpunkt tatsächlich bedient (z. B. flood, traffic, road-events).'
pagination:
type: object
description: 'Bei paginierbaren Datenart-Listen (charging, energy, events, transit, OSM-Feature-Endpunkte): der EHRLICH ausgewiesene Ausschnitt (keine stille Kappung). KANAL-ABHÄNGIGER Default für gleiche URL: direktes REST liefert die volle Liste (limit=null, returned==total, truncated=false); GPT-Actions (erkannt am OpenAI-Header) bekommen ein serverseitig gebundenes Default-Limit; MCP-Aufrufe sind gebunden, weil der MCP-Client selbst ein Default-Limit setzt. Kanalunabhängige Overrides: limit=all (oder ?all=1) erzwingt die volle Liste, limit + offset blättern gezielt. meta.pagination ist bei ALLEN Kanälen gesetzt.'
x-description-en: 'For paginable data-type lists (charging, energy, events, transit, OSM feature endpoints): the honestly reported slice (no silent capping). CHANNEL-DEPENDENT default for the same URL: direct REST returns the full list (limit=null, returned==total, truncated=false); GPT Actions (detected via the OpenAI header) get a server-side bound default limit; MCP calls are bound because the MCP client sets a default limit itself. Channel-independent overrides: limit=all (or ?all=1) forces the full list, limit + offset page explicitly. meta.pagination is set on ALL channels.'
properties:
total:
type: integer
description: Gesamtzahl der Einträge (voller Bestand).
returned:
type: integer
description: Zahl der auf dieser Seite ausgelieferten Einträge.
limit:
type: integer
nullable: true
description: Angewandtes Seiten-Limit; null bei Vollausgabe (REST-Default oder limit=all).
offset:
type: integer
description: Start-Offset der Seite.
truncated:
type: boolean
description: true, wenn hinter dieser Seite noch Einträge liegen (offset + returned < total); bei Vollausgabe false.
ErrorEnvelope:
type: object
required:
- error
- meta
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
meta:
type: object
properties:
correlation_id:
type: string
nullable: true
generated_at:
type: string
format: date-time
responses:
NotModified:
description: Not Modified. If-None-Match stimmte mit dem aktuellen ETag überein; es wird kein Body geliefert (ETag + Cache-Control bleiben erhalten).
headers:
ETag:
$ref: '#/components/headers/ETag'
Cache-Control:
$ref: '#/components/headers/CacheControl'
headers:
ETag:
description: Stabiler Entity-Tag des Response-Bodys (sha256-basiert). Nur auf erfolgreichen GET-Reads (200) gesetzt, nie auf Fehler-Envelopes/503.
schema:
type: string
CacheControl:
description: Cache-Control je Ressource ("public, max-age=<ttl>, stale-while-revalidate=<ttl>, stale-if-error=<ttl>"). TTL aus der serverseitigen CACHE_TTL-Map (z.B. wikidata 86400 s, dwd 1800 s, uba 600 s, default 300 s). stale-while-revalidate/stale-if-error erlauben einem Shared Cache (Cloudflare), bei Ablauf bzw. Origin-Fehler kurz die letzte gute Antwort weiterzuliefern. Echtzeit-Endpunkte (/api/v1/live/*) liefern stattdessen "no-store".
schema:
type: string