Baugesuche-API Schweiz: JSON, XML, MCP und Quickstart

Die API vereinheitlicht übernommene Schweizer Baupublikationen aus mehreren Quellen. Sie ist für Suche, Monitoring und technische Weiterverarbeitung gedacht, nicht als Ersatz für die amtliche Originalquelle. Aktuelle Mengen gehören nicht in einen statischen Artikel: Rufen Sie dafür /api/v1/meta auf. Dort stehen Abdeckung, Datumsgrenzen und weitere Betriebsmetadaten maschinenlesbar.

Das Wichtigste in Kürze:

• JSON-Zugriff ist innerhalb des anonymen Rate-Limits ohne Anmeldung möglich.
• Ein kostenloser Key erhöht das Limit; verbindlich sind die aktuellen X-RateLimit-*-Header und die API-Referenz.
• Filter für Kanton, Gemeinde, Text, Kategorie und Datum lassen sich kombinieren.
• Cursor-Pagination und ein Changes-Endpunkt erlauben stabile inkrementelle Synchronisation.
• Jeder Datensatz behält Provenienz und Links zur verfügbaren amtlichen Quelle.
• Kostenfreier Zugriff bedeutet nicht, dass jede Primärquelle unter derselben Open-Data-Lizenz steht oder jede Weiterverwendung zulässig ist.

Vor dem ersten Abruf: Abdeckung und Provenienz prüfen

Beginnen Sie mit zwei Fragen: Welche Kantonsquellen sind heute integriert, und welche Felder liefert die konkrete Quelle überhaupt? Der Endpunkt /api/v1/meta beantwortet die erste Frage. Die Abdeckungsseite erklärt zusätzlich in normaler Sprache, ob eine Quelle regelmässig, unregelmässig oder derzeit gar nicht integriert ist.

Die zweite Frage beantworten die Provenienzfelder im Datensatz. Je nach Quelle können Bauherrschaft, Projektverfasser, Frist, Koordinaten oder ein amtliches PDF fehlen. Ein leeres Feld ist kein Sachbeweis: Fehlt beispielsweise ein Projektverfasser im strukturierten Datensatz, folgt daraus weder, dass kein Büro beauftragt wurde, noch dass ein Auftrag frei ist.

Für einen fachlich sauberen Datenbestand sollten Sie mindestens speichern:

• interne stabile ID und kanonischen Detail-Link;
• Veröffentlichungsdatum, erste Übernahmezeit und Ihren eigenen Beobachtungszeitpunkt;
• Kanton, Gemeinde und verfügbare Standortangaben;
• Quellenname, Original-URL und gegebenenfalls Dokument-URL;
• die Roh- beziehungsweise Herkunftskennung der Publikation;
• Zeitpunkt Ihres eigenen Abrufs.

Quickstart mit Filter und Cursor

Ein erster Abruf kann ohne Key erfolgen:

text GET /api/v1/publications?canton=ZH&limit=25

Die Antwort enthält eine Liste von Publikationen und, falls weitere Ergebnisse vorliegen, einen Cursor. Geben Sie diesen beim nächsten Abruf unverändert zurück. Cursor-Pagination ist gegenüber Seitenzahlen robuster, wenn während des Abrufs neue Publikationen hinzukommen.

Typische Filter sind:

• canton für einen Kantonscode;
• municipality für eine Gemeinde;
• q für Volltext;
• category für eine regelbasierte Textkategorie;
• Datumsparameter für einen begrenzten Veröffentlichungszeitraum;
• limit für die Antwortgrösse.

Die vollständigen Parameternamen, Grenzwerte und Beispielantworten stehen auf der aktuellen Referenzseite. Verwenden Sie diese statt kopierter Parameterlisten aus Blogartikeln, weil sich ein technischer Vertrag weiterentwickeln kann.

Inkrementelle Synchronisation mit dem Changes-Endpunkt

Für einen laufenden Import ist ein wiederholter Vollabruf unnötig. Der Changes-Endpunkt liefert Datensätze nach ihrer ersten Übernahmezeit ingested_at. Quellaktualisierungen, die diesen Zeitpunkt erhalten, und Löschungen werden nicht als vollständige Änderungsereignisse ausgegeben. Ein belastbarer Ablauf sieht so aus:

1. letzten erfolgreich verarbeiteten Zeitwert next_since laden;
2. Changes-Endpunkt abrufen;
3. Datensätze idempotent anhand ihrer stabilen ID upserten;
4. Provenienz mitführen und wichtige Bestandsdatensätze periodisch separat abgleichen;
5. neuen Cursor erst nach erfolgreicher Transaktion speichern;
6. bei 429 den Retry-After-Header respektieren.

Planen Sie Wiederholungen ein. Netzfehler, Quellenausfälle und verspätete Publikationen sind bei föderierten Datenquellen normal. Die API kann das Format vereinheitlichen, aber keine in der Primärquelle fehlende Information erzeugen.

JSON, XML und Originaldokumente richtig verwenden

Das harmonisierte JSON-Modell eignet sich für kantonsübergreifende Filter und Datenbanken. XML-Endpunkte sind sinnvoll, wenn ein bestehender Prozess XML verarbeitet oder das verfügbare Originalformat benötigt. Beides ersetzt nicht die amtliche Fassung.

Beachten Sie insbesondere:

• Nicht jede Publikation besitzt ein amtliches PDF.
• Eine Dokument-URL kann zeitlich beschränkt oder zugangsgeschützt sein.
• Koordinaten können exakt, auf Gemeindeebene abgeleitet oder ganz abwesend sein.
• Kategorien entstehen regelbasiert aus Text und sind keine amtliche Klassifikation.
• Fristfelder müssen gegen die Originalpublikation geprüft werden, bevor daraus rechtliche Schritte abgeleitet werden.

Rate Limits und sicherer Produktivbetrieb

Anonyme und authentifizierte Limits werden in jeder Antwort über X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset kommuniziert. Bei Überschreitung folgt HTTP 429; Retry-After gibt die Wartezeit an. Ein Client sollte diese Header auswerten und exponentiell mit Jitter wiederholen, statt in einer engen Schleife erneut anzufragen.

Für einen produktiven Import empfehlen sich zusätzlich:

• ein klarer User-Agent mit Kontaktmöglichkeit;
• kurze Verbindungstimeouts und begrenzte Wiederholungen;
• idempotente Speicherung;
• Monitoring für Datenalter und Quellenausfälle;
• ein Link zur Originalquelle in jeder Benutzeroberfläche;
• kein Versand von Werbung allein aufgrund einer amtlichen Publikation;
• dokumentierte Lösch- und Aufbewahrungsregeln für Personendaten.

MCP für KI-Agenten

Unter /mcp steht eine MCP-Schnittstelle für Werkzeuge zur Verfügung. Sie kann Suchanfragen und strukturierte Detailabfragen vereinfachen. Ein Agent sollte Quellenlinks dennoch in seiner Antwort mitführen, Unsicherheit sichtbar machen und keine fehlenden Felder ergänzen. Für reproduzierbare Softwareintegration ist die normale API meist leichter zu testen; MCP eignet sich für explorative, werkzeuggestützte Abläufe.

Grenzen, die eine API nicht auflösen kann

Die Schweiz publiziert Baugesuche föderal. Kantone und Gemeinden verwenden Amtsblätter, eBau-Plattformen, Geoportale und kommunale Seiten. Daraus folgen drei Grenzen:

1. Keine Vollständigkeitsgarantie. Eine integrierte Quelle kann nur liefern, was sie veröffentlicht und was der Import erfolgreich übernimmt.
2. Keine einheitliche Lizenz. Technischer Zugang über diese API ändert nicht die Rechte und Pflichten der jeweiligen Primärquelle.
3. Keine rechtliche Verbindlichkeit. Für Fristen, Dossiers und Rechtsmittel ist die amtliche Behörde beziehungsweise Originalpublikation massgebend.

Wer keinen eigenen Client bauen möchte, kann dieselben Suchdimensionen über die Website, den RSS-Feed oder E-Mail-Updates nutzen. Für historische oder vergleichende Analysen sollten Sie zusätzlich den eigenen Abrufzeitpunkt und eine reproduzierbare Rohdatenkopie dokumentieren.