Grenzen

Die API ist kostenlos. Damit sie für alle schnell bleibt, hat jede App feste Grenzen. Sie gelten je App, nicht je Schlüssel oder Adresse. Reicht das für dein Projekt nicht, kannst du mehr Volumen oder ein Projektsponsoring anfragen.

Eimer

Jeder Endpunkt gehört zu einem Eimer. Ein Eimer fasst eine bestimmte Zahl Marken und füllt sich gleichmäßig nach; jede Anfrage nimmt eine Marke (manche mehr, das steht am Endpunkt). Ist er leer, kommt 429.

Eimer	Nachfüllen	Vorrat	Für
`standard`	60 pro Minute	30	Alle Daten-Endpunkte
`radar`	20 pro Minute	5	Radar und Positionen
`bild`	10 pro Minute	3	Zugzielanzeiger als Bild
`live`	6 pro Minute	2	Aufbau von Live-Strömen
`ton`	20 pro Minute	6	Tonaufnahmen der Ansagen, je Adresse
`ki`	4 pro Minute	6	Doku-Assistent, je Adresse
`seite`	60 pro Minute	30	Öffentliche Zugseiten, je Adresse
`kiGesamt`	30 pro Minute	10	Doku-Assistent, alle zusammen

Signierte Anfragen bekommen doppelte Raten und doppelten Vorrat, siehe Signierte Anfragen. Dazu höchstens 2 Live-Ströme gleichzeitig je App.

Jede Antwort sagt, wie es um den Eimer steht. Richte dich nach diesen Werten statt nach festen Zahlen; sie können sich ändern.

Header	Bedeutung
`X-RateLimit-Limit`	Vorrat des Eimers
`X-RateLimit-Remaining`	Übrige Marken
`X-RateLimit-Reset-After`	Sekunden, bis der Eimer wieder voll ist
`X-RateLimit-Bucket`	Name des Eimers
`Retry-After`	Nur bei `429`: Sekunden bis zum nächsten Versuch

{
  "code": "rate_limited",
  "message": "Zu viele Anfragen",
  "retry_after": 1.4,
  "bucket": "standard"
}

Sperre bei vielen Fehlern

Wer in zehn Minuten 300 fehlerhafte Anfragen schickt (falscher Schlüssel, unbekannte Bahnhöfe, ungültige Parameter), wird für 10 Minuten gesperrt und bekommt temporarily_blocked. Das gilt für die App und, bei falschen Schlüsseln, für die Adresse. Prüf also Eingaben, bevor du sie weiterreichst, und hör bei 401 auf, statt es weiter zu versuchen.

So kommst du gut aus

Antworten ein paar Sekunden selbst zwischenspeichern, besonders wenn viele deiner Nutzer denselben Bahnhof sehen.
Für laufend aktuelle Abfahrten den Live-Strom nehmen statt alle paar Sekunden zu fragen.
Die Liste aller Bahnhöfe einmal am Tag laden und selbst durchsuchen.
Bei 429 nach Retry-After warten, nicht sofort wiederholen.

Mehr Volumen und Projektsponsoring

Reichen die Grenzen für dein Projekt nicht, kannst du ein dediziertes Volumen anfragen. Deine App bekommt dann ein Vielfaches der Raten oben, in allen Eimern zugleich. Das passt etwa für Anzeigen an vielen Orten, Apps mit vielen Nutzern oder Auswertungen über ganz Deutschland. Mit fünffachem Volumen sind es zum Beispiel:

Eimer	Normal	Fünffach	Fünffach und signiert
`standard`	60 pro Minute	300 pro Minute	600 pro Minute
`radar`	20 pro Minute	100 pro Minute	200 pro Minute
`bild`	10 pro Minute	50 pro Minute	100 pro Minute
`live`	6 pro Minute	30 pro Minute	60 pro Minute

Ein Projektsponsoring ist für Vorhaben gedacht, die vielen nützen: offene Daten, Bildung, Barrierefreiheit, Vereine oder Apps ohne Geschäftsmodell. Dazu kann mehr Volumen gehören, Hilfe beim Einbau oder eine frühere Freischaltung neuer Bereiche. Was möglich ist, klären wir gemeinsam.

So fragst du an

Im Discord in #freischalten auf Volumen anfragen oder Projektsponsoring anfragen klicken und das kurze Formular ausfüllen: dein Projekt, was du brauchst und wofür. Daraus wird ein Ticket, das nur du und das Team sehen; dort klären wir die Einzelheiten. Wird die Anfrage genehmigt, gilt das neue Volumen sofort für deine App. Du siehst es im Portal bei der App unter Volumen.

Hilfreich für die Anfrage: welche Endpunkte du nutzt, wie viele Anfragen pro Minute zu Spitzenzeiten anfallen und ob du schon zwischenspeicherst oder den Live-Strom nutzt. Lege die App vorher im Portal an, damit das Volumen gleich der richtigen App zugeordnet werden kann.