API

Über die Schnittstelle (API) können Programme Anfragen, Antworten, Dokumente und Behörden von Frag den Bund lesen und, mit Ihrer Erlaubnis, in Ihrem Namen Anfragen stellen und bearbeiten. Sie ist für Personen mit einem Konto gedacht.

Was Sie brauchen

Für die Schnittstelle brauchen Sie ein Konto. Ohne Anmeldung antwortet sie mit «401 Anmeldung erforderlich». Ausgenommen sind nur die Abfragen, die die Seiten von Frag den Bund selbst für Besucherinnen und Besucher machen, zum Beispiel die Suche nach Behörden im Anfrageformular.

Melden Sie sich an oder erstellen Sie ein Konto.

Dokumentation

Alle Adressen, Felder und Filter sind in der interaktiven Dokumentation beschrieben (nur mit Konto sichtbar). Das Schema (OpenAPI) können Sie für Ihr Werkzeug herunterladen. Die Schnittstelle liegt unter /api/v1/ und antwortet mit JSON; für Listen gibt es auch ?format=csv.

Zugang für Programme

Programme melden sich nicht mit Ihrem Passwort an, sondern mit einem Zugangsschlüssel (Token) über OAuth 2.0 (Authorization Code). So gehen Sie vor:

  1. Registrieren Sie eine App (Konto, Einstellungen, Entwickler). Sie erhalten eine Client-ID. Redirect-Adressen müssen mit https:// beginnen. Programme in Browser oder Telefon sind öffentliche Apps und müssen PKCE verwenden.
  2. Die Person, deren Konto die App nutzt, öffnet die Anmeldeadresse und erlaubt den Zugriff. Das kann auch Sie selbst sein.
  3. Die App tauscht den Code gegen ein Token. Das Token gilt 60 Minuten; mit dem Erneuerungs-Token (gültig 30 Tage) holt die App ein neues.
# 1. Diese Adresse im Browser öffnen. Die Person meldet sich an und erlaubt den Zugriff.
https://fragdenbund.ch/account/authorize/?response_type=code&client_id=CLIENT_ID&redirect_uri=https://app.example.org/callback&scope=read:request&code_challenge=CHALLENGE&code_challenge_method=S256

# 2. Den Code, der an Ihrer Weiterleitungsadresse ankommt, gegen ein Token tauschen.
curl -X POST https://fragdenbund.ch/account/token/ \
  -d grant_type=authorization_code -d code=CODE -d client_id=CLIENT_ID \
  -d redirect_uri=https://app.example.org/callback -d code_verifier=VERIFIER

# 3. Die API mit dem Token aufrufen.
curl -H "Authorization: Bearer ACCESS_TOKEN" "https://fragdenbund.ch/api/v1/request/?format=json"

Wer Zugriff gegeben hat, kann ihn jederzeit unter Einstellungen, Apps mit Zugriff wieder entziehen. Eine App kann nur das tun, was bei der Erlaubnis angezeigt wurde:

Berechtigung Erlaubt der App
read:user Kann Sie als Nutzer:in auf Frag den Bund identifizieren
read:profile Kann Ihre Profilinformationen sehen
read:email Kann Ihre E-Mail-Adresse sehen
read:request Kann Ihre (privaten) Anfragen sehen
make:request Kann Anfragen in Ihrem Namen stellen
write:request Anfragen bearbeiten
write:message Nachrichten hinzufügen und bearbeiten
write:attachment Anhänge hinzufügen und bearbeiten
follow:request Folge/Entfolge Anfragen
read:document Kann Ihre (privaten) Dokumente sehen

Nutzungsgrenzen

Damit die Seite für alle schnell bleibt, gelten Grenzen pro Minute:

  • Mit Konto: 300 Aufrufe.
  • Suchen (Behörden, Anfragen, Textsuche): 60 Aufrufe.
  • Ohne Konto, bei den wenigen offenen Abfragen: 120 Aufrufe.

Wird eine Grenze erreicht, antwortet die Schnittstelle mit «429» und nennt in Retry-After, wie viele Sekunden Sie warten sollen. Bitte bauen Sie das in Ihr Programm ein.

Was Sie nicht sehen

Die Schnittstelle zeigt dieselben Daten wie die Website. Nicht öffentliche Anfragen, Antworten, die noch nicht freigegeben sind, Namen von Anfragenden, die ihn nicht veröffentlichen, und E-Mail-Adressen von Behörden, die wir nicht anzeigen, fehlen auch hier.

Regeln

Es gelten die Nutzungsbedingungen, im Besonderen der Abschnitt zur Schnittstelle, und die Datenschutzerklärung. Wer die Grenzen umgeht oder Daten Dritter missbraucht, kann gesperrt werden.

Fragen und Fehler: info@fragdenbund.ch