API-Dokumentation

Förder-API v1.

Die Förder-API liefert die BundesBonus-Datenbank als JSON: aktive Förderprogramme mit Konditionen, Kriterien, Antragsschritten, offiziellen Quellen und regionaler Geltung bis auf Gemeinde-Ebene. Basis-URL: https://api.bundes-bonus.de

Authentifizierung

Jeder Request braucht einen Bearer-Key im Authorization-Header. Keys vergeben wir im Early-Access persönlich — Anfrage über die Partner-Seite. Behandeln Sie den Key wie ein Passwort: Er gehört in Server-Code oder Umgebungsvariablen, nie in Frontend-JavaScript.

curl -s "https://api.bundes-bonus.de/v1/meta" \
  -H "Authorization: Bearer bb_live_IHRKEY"

Endpoints

Methode	Pfad	Zweck & Parameter
GET	/v1/meta	API-Version, Anzahl aktiver Programme, Themen-Liste. Geeignet als erster Test nach Key-Erhalt.
GET	/v1/programme	Programm-Liste. Parameter: q (Volltext), thema, region (Slug), audience (privat\|unternehmen), foerderart, limit (max 50), offset. Die Antwort nennt limit und offset in der tatsächlich angewandten Höhe. Ausnahme: q ist relevanz-sortiert und liefert höchstens 20 Treffer — offset ist dort nicht zulässig (400).
GET	/v1/programme/{slug}	Voll-Detail eines Programms: Beschreibung, Konditionen, Kriterien, FAQ, Antragsschritte, offizielle Quellen und Links.
POST	/v1/match	Situations-Matching wie im Förder-Check: PLZ/Stadt + Thema + Filter → passende Programme mit Betrags-Spanne.
GET	/v1/regionen/search	Autocomplete für Städte, Gemeinden und Landkreise. Parameter: q, limit (max 10).
GET	/v1/plz/{plz}	PLZ → Region (Stadt vor Gemeinde vor Bundesland/Landkreis aufgelöst).

Beispiel: Situations-Matching

curl -s -X POST "https://api.bundes-bonus.de/v1/match" \
  -H "Authorization: Bearer bb_live_IHRKEY" \
  -H "Content-Type: application/json" \
  -d '{"plzOrStadt": "80331", "situation": "energie"}'

Der match-Endpoint akzeptiert dieselben Filter wie der Förder-Check auf bundes-bonus.de: wohnform, kinder, einkommen, foerderart sowie audience und für Unternehmens-Anwendungen b2bPhase, b2bGroesse, b2bFokus.

Limits & Fehler

Early-Access-Keys haben standardmäßig 60 Requests pro Minute und ein Tages-Kontingent von 5.000 Requests (Reset Mitternacht UTC) — wenn Ihre Integration mehr braucht, sprechen Sie uns an, die Limits sind pro Key konfigurierbar. Zusätzlich gilt eine absenderbezogene Drossel gegen Lastspitzen. Antworten tragen Cache-Control: no-store; clientseitiges Caching von wenigen Minuten ist trotzdem sinnvoll und erlaubt.

Server-zu-Server: Die API setzt bewusst keine CORS-Header — Aufrufe direkt aus dem Browser sind nicht vorgesehen und schlagen an der Same-Origin-Policy fehl. Das ist Absicht: Ihr Key gehört auf Ihren Server, nicht in ausgeliefertes JavaScript, wo ihn jeder Besucher auslesen könnte. Rufen Sie die API aus Ihrem Backend auf und liefern Sie das Ergebnis an Ihre Seite aus. Wenn Sie eine reine Frontend-Lösung brauchen, ist das Förder-Widget der richtige Baustein — es läuft ohne Key auf Ihrer Domain.

Status	Bedeutung
400	Ungültige Parameter (z. B. PLZ nicht 5-stellig, Slug-Format falsch, offset zusammen mit q).
401	Authorization-Header fehlt oder Key unbekannt.
403	Key deaktiviert.
404	Ressource nicht gefunden (Programm-Slug, PLZ ohne Region).
429	Rate-Limit erreicht — Retry-After-Header beachten.

Nutzungsbedingungen (Early-Access)

Attribution: Wo Förderdaten aus der API für Endnutzer sichtbar werden, nennen Sie „Förderdaten: BundesBonus" mit Link auf bundes-bonus.de. Jede API-Antwort enthält das passende attribution-Feld.
Keine Weiterlizenzierung: Die Daten sind für Ihre eigene Website bzw. Anwendung bestimmt — nicht für den Weiterverkauf oder die Weitergabe als Datenbank an Dritte (§ 87a UrhG).
Ohne Gewähr: Wir pflegen die Daten sorgfältig und laufend, können aber Vollständigkeit und Fehlerfreiheit nicht garantieren. Verbindlich sind allein die offiziellen Förderstellen — jede Detail-Antwort verlinkt deren Quellen. Die API ersetzt keine Rechts- oder Steuerberatung.
Verfügbarkeit: Early-Access heißt: keine vertraglich zugesicherte Verfügbarkeit. Geplante größere Wartungen kündigen wir Partnern per E-Mail an.