Paginierung und Limits

Die meisten InfraNode-Endpunkte liefern kompakte Datensätze. Einige wenige liefern große Listen: alle Ladesäulen, alle Energieanlagen oder alle ÖPNV-Haltestellen einer Großstadt sind schnell mehrere Megabyte. Solche Listen sind paginierbar, damit KI-Agenten (MCP) und GPT Actions nicht an ihren Größenlimits scheitern, Bulk-Nutzer der REST-API aber weiterhin alles in einem Aufruf bekommen.

Der Kernpunkt: Paginierung ist optional und betrifft nur große, statische Listen, niemals Live-Daten. Der Standard hängt zudem vom Aufrufkanal ab. Beides ist über meta.pagination in jeder Antwort transparent.

Was ist paginierbar, was nicht

Paginiert werden ausschließlich die großen, sich langsam ändernden Standort-/Bestandslisten. Live-Daten bleiben immer vollständig, weil sie klein und tagesaktuell sind und ein Ausschnitt dort keinen Sinn ergäbe.

Kategorie	Beispiele	Paginierbar
Große statische Listen	`energy`, `charging` (Standorte), `transit` (Haltestellen), `events` sowie OSM-Listen wie `education`, `playgrounds`, `post-boxes`	Ja, optional
Live- und Kompaktdaten	`weather`, `air`, `traffic`, `transit/departures`, `charging-status`, `water-level`, `flood`, `power-load`	Nein, immer vollständig

Für die Haltestellensuche gibt es zusätzlich ?q= (Name) und ?near=lat,lon (Umkreis) auf transit, damit man gezielt wenige Treffer statt der ganzen Stadt bekommt.

Kanal-abhängiger Standard

Ohne expliziten limit-Parameter hängt die Standard-Seitengröße davon ab, über welchen Kanal der Aufruf kommt. So bleibt die REST-API für bestehende Bulk-Nutzer unverändert, während die zwei Kanäle mit harten Größengrenzen automatisch geschont werden.

Kanal	Standard	Warum
Direktes REST (`/api/v1`)	voll (kein Limit)	Data-Puller bekommen alles in einem Aufruf, kein Bruch.
GPT Actions	gebunden (50)	Erkannt an den OpenAI-Headern, serverseitig erzwungen, damit die Antwort unter dem Action-Größenlimit bleibt.
MCP-Server	gebunden (50)	Der MCP-Client setzt das Limit selbst, der Agent-Kontext bleibt schlank.

Wichtig zu wissen: Dieselbe URL kann über zwei Kanäle unterschiedlich viele Einträge liefern. Das ist Absicht und in jeder Antwort an meta.pagination ablesbar (siehe unten), sodass nie unklar bleibt, ob ein Ausschnitt oder der volle Bestand vorliegt.

Damit ein gemeinsamer Zwischenspeicher diese kanal-abhängige Antwort nicht verwechselt, werden GPT-Actions-Antworten nicht am Edge zwischengespeichert: Die API sendet für GPT-Requests Cache-Control: no-store und Cloudflare nimmt diesen Traffic zusätzlich per Regel vom Edge-Cache aus. Sonst würde derselbe geteilte Cache unter einer URL die falsche Variante an den jeweils anderen Kanal ausspielen: REST bekäme die gebundene 50er-Antwort, GPT die vollständige, unter Umständen mehrere Megabyte große Antwort.

Parameter

Parameter	Bedeutung
`limit`	Anzahl Einträge pro Seite. Ganzzahl ab `1`, hart gedeckelt auf 200 (`MAX_LIMIT`). Ein größerer Wert liefert eine 200er-Seite statt eines Fehlers.
`offset`	Startposition für das Blättern (Default `0`). Ein Offset jenseits des Bestands liefert eine leere Seite mit Status `200`, keinen Fehler.
`limit=all` oder `?all=1`	Kanalunabhängiger Voll-Schalter: erzwingt die komplette Liste, auch über GPT Actions und MCP. Der self-documenting Weg, bewusst alles zu holen.

meta.pagination

Jede paginierbare Antwort trägt einen pagination-Block im meta-Objekt. Er macht den Ausschnitt ehrlich sichtbar, es gibt keine stille Kürzung.

Feld	Inhalt
`total`	Gesamtzahl der Einträge im vollen Bestand.
`returned`	Zahl der in dieser Antwort enthaltenen Einträge.
`limit` / `offset`	Die tatsächlich angewandte Seitengröße und Startposition.
`truncated`	`true`, wenn ein Ausschnitt vorliegt (es gibt mehr als `returned`), sonst `false`. Bei Vollausgabe gilt `returned == total` und `truncated: false`.

Vollständige Geometrie bei Verkehr

Der traffic-Endpunkt (Live) wird nicht paginiert, sondern schlank gehalten: die rohen Polylinien-Geometrien der Baustellen sind standardmäßig ausgeblendet, weil sie die Antwort vervielfachen und für die meisten Aufrufe irrelevant sind. Kartenanwendungen holen sie explizit dazu:

https://infranode.dev/api/v1/cities/koeln/traffic?include=geometry

Alternativ wirkt ?full=1 identisch. Ohne diesen Parameter bleibt der amtliche Inhalt (Titel, Beschreibung, Ort, Betroffenheit) vollständig erhalten, nur die Polylinie fehlt.

Beispiele

Erste 20 Ladesäulen-Standorte, ab dem 40. Eintrag:

https://infranode.dev/api/v1/cities/berlin/charging?limit=20&offset=40

Alle Energieanlagen in einem Aufruf, egal über welchen Kanal:

https://infranode.dev/api/v1/cities/berlin/energy?limit=all

Haltestelle per Name finden (liefert wenige Treffer mit stop_id):

https://infranode.dev/api/v1/cities/hamburg/transit?q=Alsterdorf