# Baugesuche Schweiz — API and MCP reference Independent aggregator of imported official construction publications and register entries. Search and filter access is free within the published rate limits. Sources include amtsblattportal.ch, Geneva SITG, Neuchâtel SITN and weekly gazettes in Uri, Glarus and Jura. An integration is not proof of complete or current capture. - Base URL: https://baugesucheschweiz.switchli.ch - Human method, source status and corrections: https://baugesucheschweiz.switchli.ch/abdeckung - Directory: https://baugesucheschweiz.switchli.ch/baugesuche — all 26 cantons, including sources not integrated - Integrated canton codes: AR BE BL BS GE GL JU NE NW OW SH SO SZ TI UR VS ZG ZH - Live record counts and taxonomy: https://baugesucheschweiz.switchli.ch/api/v1/meta - OpenAPI: https://baugesucheschweiz.switchli.ch/api/v1/openapi.json — Swagger: https://baugesucheschweiz.switchli.ch/api/docs - Human quickstart and key form: https://baugesucheschweiz.switchli.ch/api - MCP, streamable HTTP: https://baugesucheschweiz.switchli.ch/mcp ## Meaning and limits Counts describe stored publications/register entries, not unique building projects, approvals, construction starts or market size. Re-publications can describe the same project. Categories are multi-label text rules, not official classifications. Municipality counts in the API count distinct source labels; local pages use the official municipality registry and reviewed aliases. A source municipality can be an administrative publication office rather than the actual construction site. publication_date is normally the source's publication date, but in Geneva it is the filing date (date de dépôt). ingested_at is the first import timestamp, not a source verification or last modification timestamp. Regular integrations are scheduled automatically; Geneva is irregular. Fetch failures and missing fields remain possible. Do not infer freshness of one source from a global date. The competent authority's official publication or dossier is authoritative, whether HTML, PDF or another format. Not every entry has a PDF, a signature or a deadline. Missing deadlines mean unavailable; some imported dates are derived from a stated duration and must be checked against the official notice. These data do not replace legal advice or the official process. Technical access is not a blanket reuse licence. No unlimited retention or permanent external-document access is guaranteed. Data may be corrected or removed. The legacy boolean infinite_history remains in /meta for compatibility but is false. Use retention_policy and coverage_url for context. ## Formats and authentication JSON is the canonical harmonized model bgch.v1. XML mirrors its field structure; the namespace remains https://baugesuche.switchli.ch/schema/v1 as a stable schema identifier. It is not a navigation URL. Dates are ISO 8601; timestamps include a timezone where available. Website dates are displayed as DD.MM.YYYY. Anonymous: 120 requests/hour/IP. A free verified key raises this to 5000/hour. Send Authorization: Bearer bg_. Request a key with POST /api/v1/keys and a JSON body containing email. The double-opt-in link reveals the key once; only its hash is stored. Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; on 429 respect Retry-After. Do not put credentials in query strings. ## Endpoints - GET /api/v1/publications: filtered list. canton, category and municipality accept comma-separated values. q searches title, description, municipality and project framer. from/to bound publication_date; ingested_since filters first import time. limit is 1..200 (default 50); cursor is returned as next_cursor. Response: items, next_cursor, total. Results use publication_date descending. - GET /api/v1/publications/{id}: one bgch.v1 JSON record. - GET /api/v1/publications/{id}.xml: harmonized XML. - GET /api/v1/publications/{id}/original.xml: stored source XML, if available; 404 if absent. Not all source integrations publish XML. - GET /api/v1/changes?since=&limit=200: first-ingestion stream. limit 1..1000. Response: items, next_since, count. Ordered by ingested_at; same-time batches are kept together. This is NOT a complete update/deletion log. Source refreshes that preserve ingested_at and removals are not reported as deltas. Reconcile important records periodically and keep your own observation times. - GET /api/v1/meta: current database counts, date bounds, taxonomy, retention and coverage references. Counts do not measure source completeness or crawler indexing. For pagination, keep filters unchanged and return next_cursor until it is null. For /changes, upsert by id and advance next_since only after successful processing. Neither endpoint is a transactionally frozen export while source imports run. ## bgch.v1 fields - id: opaque internal identity; publication_number: source reference, may be empty. - source: tenant, subrubric, official_detail_url, official_pdf_url (may be empty). - canton: source canton code; CH is a cross-cantonal/unknown administrative bucket, not a 27th canton. - municipality: name as represented in the source record, slug for navigation. - publication_date, expiration_date, entry_deadline: ISO date or null. Their legal meaning depends on the source; see date qualifications above. - title, description: source-derived text, not evidence of approval or a free contract. - categories: multi-label taxonomy codes. - building_contractor, project_framer, representation, landowner: available source fields; personal information can be reduced. Publication is not consent to advertising. - location.raw, parcel, zone, coordinates, case_number, inspection_office, legal_remedy, extras: optional source-derived fields; missing values are not inferred. - ingested_at: first import timestamp. - links: html, json, xml, xml_original, pdf. html/pdf may be empty for records without a usable local route; a PDF endpoint may return 404 or an upstream error. - _disclaimer: official-source precedence and limits of this representation. ## Categories - `energie_heizung` — Energie & Heizung - `solar_pv` — Solar & PV - `neubau_wohnen` — Neubau Wohnen - `umbau_sanierung` — Umbau & Sanierung - `abbruch` — Abbruch - `kleinbauten` — Kleinbauten - `gewerbe_industrie` — Gewerbe & Industrie - `landwirtschaft` — Landwirtschaft - `aussenanlagen_infrastruktur` — Aussenanlagen & Infrastruktur - `sonstiges` — Sonstiges ## Examples Filtered API request: `GET https://baugesucheschweiz.switchli.ch/api/v1/publications?canton=ZH&category=energie_heizung&limit=5` Filtered human search: `https://baugesucheschweiz.switchli.ch/?kanton=ZH&kategorie=energie_heizung` RSS uses the website parameter names: `https://baugesucheschweiz.switchli.ch/feed.xml?kanton=ZH&gemeinde=Winterthur` The stable RSS guid is urn:baugesuche:, independent of the HTML URL. RSS dates are RFC 822, rendered at midnight UTC as a day-precision convention. Geneva filing dates and invalid/absent source dates are not emitted as RSS pubDate. The API preserves Geneva's original date field and its documented meaning. ## MCP tools - search_baugesuche(query?, canton?, category?, municipality?, date_from?, date_to?, limit<=50) - get_baugesuch(id) - get_coverage() MCP uses anonymous per-IP rate limits. Tools provide records and source links; a successful tool response is not evidence of a citation in a consumer AI answer. Use exact official links when verifying a notice and cite the method when comparing aggregated data. This optional reference is navigation support, not special AI markup.