# Immonika - Deutsches Immobilienportal
> Immobiliensuche mit strukturierten Daten für Kauf, Miete und Pacht

## Über dieses Portal
Immonika ist ein deutsches Immobilienportal, technisch ausgelegt für bis zu rund 500.000 Inserate
in mehr als 10.000 Orten (Kapazitätsziel der Plattform — nicht der aktuelle Live-Bestand).
Der aktuelle Bestand ist maschinenlesbar unter [Städte mit Inseraten](https://immonika.de/api/cities.json)
(`totalCount`, `listingCount` pro Ort).
Alle Daten werden täglich aktualisiert.
Kein Login nötig. Filter erfolgen über URL-Pfade (statische Seiten), nicht über Formulare.

## Empfohlener Einstieg für KI-Agenten
- [OpenAPI Spec](https://immonika.de/openapi.json): OpenAPI 3.0 Standardpfad für Scanner
- [Swagger-Alias](https://immonika.de/swagger.json): identischer OpenAPI-Inhalt
- [OpenAPI unter /api/](https://immonika.de/api/openapi.json): gleiche Spec unter /api/
- [API-Dokumentation](https://immonika.de/api/docs/): menschenlesbare API-Doku (HTML, DE)
- [KI-Index](https://immonika.de/ai-index.json): kompakter KI-Einstieg (Endpoints-JSON)
- [API-Katalog](https://immonika.de/.well-known/api-catalog): RFC 9727 Linkset (Datei [api-catalog](https://immonika.de/api/api-catalog)); kein ChatGPT-Plugin
- [Ablauf](https://immonika.de/api/workflow): Suche → Filtern → Auswahl → Vergleich → Kontakt (`type: agentWorkflow`); kein Chat-Server
- [Suchindex](https://immonika.de/api/search): jüngste Inserate (`type: searchIndex`); Filter city/rooms/price_max clientseitig an `items[]` (nicht `?city=` anhängen — Query ändert die Datei nicht)
- [Anbieter-Index](https://immonika.de/api/anbieter): alle öffentlichen Firmen und Makler (`type: agentIndex`); Filter name/city/role an `items[]`; Alias [agents](https://immonika.de/api/agents)
- [Listings Discovery](https://immonika.de/api/listings.json): Übersicht aller Einstiegspunkte (`type: discovery`)
- [Städte mit Inseraten](https://immonika.de/api/cities.json): alle Orte mit mindestens einem Inserat
- [Beispiel Berlin Listings](https://immonika.de/Berlin/api/listings.json): Pattern `/{ortSlug}/api/listings.json`
- [Beispiel Berlin Stadtteile](https://immonika.de/Berlin/api/stadtteile.json): Pattern `/{ortSlug}/api/stadtteile.json`
- [Beispiel Berlin Makler](https://immonika.de/Berlin/api/makler.json): Pattern `/{ortSlug}/api/makler.json`
- [Beispiel Anbieterprofil](https://immonika.de/Anbieter/CF242MGQHWBP/api/agent.json): Pattern `/Anbieter/{aeHash}/api/agent.json`
- [Beispiel Anbieter-Inserate](https://immonika.de/Anbieter/CF242MGQHWBP/api/listings.json): Pattern `/Anbieter/{aeHash}/api/listings.json`
- Pattern `/Anbieter/{aeHash}/{meHash}/api/agent.json`: Makler-Personenprofil (mit parentOrganization)
- [Beispiel Kaufen Berlin](https://immonika.de/Berlin/Kaufen/api/listings.json): Pattern `/{ortSlug}/{vermarktungsart}/api/listings.json`
- [Beispiel Exposee listing.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/listing.json): Einzelobjekt (RealEstateListing, dateModified, amenities, energy, contactIntent, parentFeed)
- Markdown-Fassung je Inserat: Pattern `/{ortSlug}/{vermarktungsart}/{objektart}/{unterkategorie}/{exposeeId}/index.md` (llms.txt-v2-Konvention: gleiche URL wie die Seite, Endung `.md`); im Seitenkopf als `rel="alternate" type="text/markdown"` verlinkt, Feld `markdownUrl` in der listing.json
- [Orts-Sitemap HTML](https://immonika.de/sitemap.html): menschenlesbare Alternative
- [Sitemap XML](https://immonika.de/sitemap.xml): maschinenlesbare Alternative

**Wichtig:** [Listings Discovery](https://immonika.de/api/listings.json) ist **kein** Gesamt-Feed aller Inserate.
Es enthält `type: "discovery"` und Verweise - keine `items`-Liste mit Exposees.

## Maschinenlesbare Endpunkte
- [API-Dokumentation](https://immonika.de/api/docs/): öffentliche API-Dokumentation (HTML, DE)
- [OpenAPI Spec](https://immonika.de/openapi.json): OpenAPI 3.0 (Standardpfad für Scanner)
- [Swagger-Alias](https://immonika.de/swagger.json): identischer OpenAPI-Inhalt
- [OpenAPI unter /api/](https://immonika.de/api/openapi.json): gleiche Spec unter /api/
- [API-Übersicht](https://immonika.de/api/index.html): HTML-Links zu allen API-Ressourcen
- [KI-Index](https://immonika.de/ai-index.json): kompakter KI-Einstieg (llms, Sitemaps, API-Root)
- [API-Katalog](https://immonika.de/.well-known/api-catalog): RFC 9727; Datei [api-catalog](https://immonika.de/api/api-catalog)
- [Ablauf](https://immonika.de/api/workflow): definierter Flow inkl. `nextActions`; Alias [workflow.json](https://immonika.de/api/workflow.json)
- [Suchindex](https://immonika.de/api/search): jüngste Inserate, Kappe 25000; Filter Ort/Zimmer/Preis an `items[]`, nicht als Query-String; Alias [search.json](https://immonika.de/api/search.json)
- [Anbieter-Index](https://immonika.de/api/anbieter): alle öffentlichen Firmen und Makler; Alias [anbieter.json](https://immonika.de/api/anbieter.json) und [agents](https://immonika.de/api/agents)
- [Listings Discovery](https://immonika.de/api/listings.json): Discovery-Stub; Start hier bei Suche nach "listings"
- [Städte mit Inseraten](https://immonika.de/api/cities.json): authoritative Ortliste (`listingCount`, Ziel-URL pro Ort)
- Markdown-Mirrors: Pattern `/{ortSlug}/{vermarktungsart}/{objektart}/{unterkategorie}/{exposeeId}/index.md` — Teilmenge der listing.json als Fließtext, `text/markdown`, `X-Robots-Tag: noindex` (die HTML-Seite ist die indexierbare Fassung). Nicht in der Sitemap; Entdeckung über den `rel=alternate`-Link im Seitenkopf
- [Beispiel Berlin Listings](https://immonika.de/Berlin/api/listings.json): Pattern `/{ortSlug}/api/listings.json` (RealEstateListing, Feld `items`)
- [Beispiel Berlin Stadtteile](https://immonika.de/Berlin/api/stadtteile.json): Pattern `/{ortSlug}/api/stadtteile.json` (Centroid lat/lng)
- [Beispiel Kaufen Berlin](https://immonika.de/Berlin/Kaufen/api/listings.json): gefiltert nach Vermarktungsart
- [Beispiel Häuser Kaufen Berlin](https://immonika.de/Berlin/Kaufen/H%C3%A4user/api/listings.json): gefiltert nach Objektart
- Pattern `/{ortSlug}/.../{unterkategorie}/api/listings.json`: z. B. 3-Zimmer, Baugrund
- [Makler Discovery](https://immonika.de/api/makler.json): Wegweiser auf Orts-Empfehlungen; globaler Katalog ist [Anbieter-Index](https://immonika.de/api/anbieter)
- [Beispiel Berlin Makler](https://immonika.de/Berlin/api/makler.json): Makler-Empfehlungen (20 km Umkreis); `qualityIndexScore` 0–100 relativ zum höchsten `ranking` in dieser Ortsliste (100 = Bester im Ort)
- [Beispiel Berlin Makler HTML](https://immonika.de/Berlin/Makler/): menschenlesbare Makler-Übersicht
- [Beispiel Anbieterprofil](https://immonika.de/Anbieter/CF242MGQHWBP/api/agent.json): Schema.org RealEstateAgent; `qualityIndexScore` 0–100 relativ zum höchsten öffentlichen `ranking` im Portal (`qualityIndexScope: portal`)
- [Beispiel Anbieter-Inserate](https://immonika.de/Anbieter/CF242MGQHWBP/api/listings.json): Inserate des Anbieters
- Pattern `/Anbieter/{aeHash}/{meHash}/api/agent.json`: Makler-Personenprofil
- Pattern `/Anbieter/{aeHash}/{meHash}/api/listings.json`: Inserate des Maklers
- [Beispiel Exposee listing.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/listing.json): contactIntent v3, fieldDefinitions, agentWorkflow
- [Beispiel contact-request.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/contact-request.json): Kontakt-Schema; POST an [kontakt.php](https://service.immonika.de/kontakt.php)
- [API-Sitemap](https://immonika.de/api/sitemap-api.xml): alle aktiven Orts-API-URLs (Listings + Makler)
- [Sitemap XML](https://immonika.de/sitemap.xml): hierarchische Sitemap aller Index- und Exposee-Seiten
- [Sitemap Indexseiten](https://immonika.de/sitemap-indexseiten.xml): alle indexierbaren Ort- und Kategorieseiten
- [Sitemap Exposees](https://immonika.de/sitemap-exposees.xml): alle aktiven Exposee-Seiten
- [Anbieter-Sitemap](https://immonika.de/anbieter-sitemap.xml): Anbieterseiten mit Objekten und gültigem Impressum
- [Orts-Sitemap HTML](https://immonika.de/sitemap.html): menschenlesbare Ortsübersicht
- [llms.txt](https://immonika.de/llms.txt): diese Datei

**Hinweise:**
- `ortSlug` aus [Städte mit Inseraten](https://immonika.de/api/cities.json) verwenden (URL-freundlich, kann von Schreibweise des Ortsnamens abweichen).
- Unter **Kaufen** heißt die Objektart **Eigentumswohnungen** (nicht "Wohnungen"); **Wohnungen** gilt bei **Mieten**.
- Orte ohne Inserate: `/{ortSlug}/api/listings.json` liefert HTTP 200 mit leerem `items`-Array.

## Nicht für KI-Crawler
- /listings.json (ohne `/api/`-Prefix im Root) - existiert nicht; nutze [Listings Discovery](https://immonika.de/api/listings.json)
- /{ortSlug}/leanlist.json - nur Browser-JavaScript (Objektlisten-Widgets)
- /{ortSlug}/extendedleanlist.json - nur Kartensuche im Browser

## HTML-Seiten
Index- und Exposee-Seiten enthalten JSON-LD (WebSite, ItemList, RealEstateListing,
RealEstateAgent, BreadcrumbList). KI-Bots dürfen HTML-Seiten crawlen (siehe [robots.txt](https://immonika.de/robots.txt)).
Exposee-URLs: `/{ortSlug}/.../{hash}/` (HTML) bzw. `items[].listingApi` → `.../api/listing.json` (JSON).

## Datenstruktur
Hierarchie: Ort > Vermarktungsart (Kaufen/Mieten/Pachten) > Objektart > Unterkategorie

**Discovery-JSON** ([Listings Discovery](https://immonika.de/api/listings.json)): `schemaVersion`, `type`, `entryPoints`, `perCityListingsPattern`, `perCityStadtteilePattern`, `hint`

**Stadtteile-JSON** ([Beispiel Berlin](https://immonika.de/Berlin/api/stadtteile.json)): `ort`, `totalCount`, `items[]` mit `name`, `lat`, `lng`

**Daten-JSON** ([Beispiel Berlin Listings](https://immonika.de/Berlin/api/listings.json)): zusätzlich `generatedAt`, `totalCount`,
`truncated`, `maxItems` (500 auf Ort- und Vermarktungsart-Ebene). Auf Ortsebene: `stadtteileApi`, `districtFilterHint`.
Array `items` mit RealEstateListing-Feldern: name (inkl. Bezirk, z. B. „Häuser in Berlin · Friedrichsfelde"),
`district`, `stadtteil`, offers.price, numberOfRooms, floorSize, address.addressSubLocality, yearBuilt, url, listingApi, datePosted

**Exposee-Detail** (`…/api/listing.json`): zusätzlich `dateModified` (Inhaltsdatum), `amenities` (physische Ausstattung), `energy` (Energieausweis, falls vorhanden), `contactIntent`.

**Makler-JSON** ([Beispiel Berlin Makler](https://immonika.de/Berlin/api/makler.json)): `qualityIndexScore` 0–100 relativ zum höchsten `ranking` dieser Ortsliste (100 = Bester im Ort, nicht CSV-Maximalstufe). Profil-`agent.json`: gleicher Score relativ zum Portal-Maximum.

**Ablauf (Suche → Kontakt):**
1. [Ablauf](https://immonika.de/api/workflow) lesen (`steps[]`, `nextActions`)
2. [Suchindex](https://immonika.de/api/search) laden und `items[]` filtern
3. Ein oder zwei `items[].listingApi` laden (vergleichen: Preis, Zimmer, Ort)
4. Kontakt nur über `contactIntent.agentWorkflow` — nicht das HTML-Formular

**Suche (Beispiel „3-Zimmer in Celle unter 300000 Euro“):**
1. [Suchindex](https://immonika.de/api/search) laden — ohne Query-String
2. Clientseitig filtern: `city`/`citySlug`, `numberOfRooms`, `offers.price` (nicht `?city=` anhängen)
3. Pagination: `page` ab 1, `pageSize` 50 — `items` selbst schneiden
4. Kein Treffer oder `truncated: true`: [Städte](https://immonika.de/api/cities.json) → `/{ortSlug}/api/listings.json`

**Anbieter (Beispiel „Makler in Berlin“):**
1. [Anbieter-Index](https://immonika.de/api/anbieter) laden
2. Clientseitig filtern: `city`, `role` (`organization` oder `person`), `name`/`organization`
3. Profil: `items[].agentApi` — Inserate des Anbieters: `items[].listingsApi`
4. Orts-Empfehlungen (20 km): `/{ortSlug}/api/makler.json`

**Stadtteil-Abfrage (Beispiel „EFH in Friedrichsfelde“):**
1. [Städte mit Inseraten](https://immonika.de/api/cities.json) → `ortSlug` (z. B. Berlin)
2. [Beispiel Berlin Stadtteile](https://immonika.de/Berlin/api/stadtteile.json) → gültige Bezirksnamen (`items[].name`)
3. [Beispiel Berlin Listings](https://immonika.de/Berlin/api/listings.json) oder [Häuser Kaufen Berlin](https://immonika.de/Berlin/Kaufen/H%C3%A4user/api/listings.json)
4. Clientseitig filtern: `items.filter(i => i.district === "Friedrichsfelde")` (oder `stadtteil` / `address.addressSubLocality`)

## Kontaktanfragen durch KI-Agenten (Variante B)

**WICHTIG — Einstieg für Agenten (nicht das HTML-Formular scrapen):**
1. [Beispiel contact-request.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/contact-request.json) laden (Schema + JSON-Feld-Mapping) — oder [Beispiel listing.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/listing.json) → `contactIntent` v3.
2. `fieldDefinitions` / `jsonFieldMap` lesen (z. B. `firstName` → `Vorname`, Pflichtfelder, `exposeeContext`).
3. `agentWorkflow` befolgen: GET Schema → POST `contactIntent.endpoint` mit **`Content-Type: application/json`** (snake_case/camelCase) **oder** `application/x-www-form-urlencoded`.
4. JSON-Antwort: Header `Accept: application/json` (Feld `mode=agent` bei form-urlencoded). Erfolg/Fehler: `contact-request.json` → `successResponses` / `errorResponses` (Feld `status`).
5. HTML-Exposée: `#immonika-agent-contact-config` und `data-agent-schema` am `<form>` zeigen Schema-URL und POST-Ziel.

- Endpoint: [service.immonika.de/kontakt.php](https://service.immonika.de/kontakt.php) (POST; Maschinenlesbar nur über `contactIntent` in `listing.json`)
- HTML-Formular auf der Exposée-Seite: klassisches `<form method="post">` — nur für Menschen; Agenten nutzen `listing.json` → `contactIntent`.
- **Erstkontakt Mensch:** DOI-Pflicht — Nutzer muss Bestätigungsmail klicken (`humanStepsRequired: email_doi_confirmation`).
- **KI-Agent (`VermittlerTyp=ki-agent`, JSON):** `sent` bedeutet angenommen. Die Zustellung an den Anbieter kann von der Freigabe des Interessenten abhängen. Kein zweiter Status.
- **Folgekontakt (verifizierte E-Mail / Allowlist, Mensch):** Kein erneutes DOI; Captcha entfällt in der Regel. Limits: 120/h, 400/24h pro E-Mail; **1 Anfrage pro Exposée pro 7 Tage**.
- **Einwilligung Weiterleitung (Textversion v2):** Feld `Einverstaendnis=yes` — bei Erstkontakt Pflicht; nach einmaliger Bestätigung pro E-Mail in Allowlist gespeichert (`consentCached`)
- **JSON-Modus:** Header `Accept: application/json` oder `mode=agent` — Antworten: `sent`, `doi_required`, `consent_required`, `duplicate_exposee`, `rate_limited`, `validation_error`
- **KI-Kennzeichnung:** Optionales Feld `VermittlerTyp=ki-agent` — Anbieter-Mail mit Hinweis in Betreff und Body (nur Label, kein Sicherheits-Bypass)
- Agenten dürfen DOI und Einwilligung nicht umgehen; nach DOI und gespeicherter Einwilligung dürfen sie für dieselbe E-Mail weitere Objekte ohne erneute Checkbox anfragen

## RSL-Lizenz (Really Simple Licensing 1.0)
- [RSL-Lizenzdatei](https://immonika.de/license.xml): Really Simple Licensing 1.0
- [robots.txt](https://immonika.de/robots.txt): Kommentar verweist auf [license.xml](https://immonika.de/license.xml)
- [AGB Nutzungsrechte](https://immonika.de/agb.html#nutzungsrechte): vertragliche Grundlage für Anbieter
- Maschinenlesbare APIs unter `/api/` und `/{ortSlug}/.../api/`: KI-Agenten dürfen lesen, crawlen,
  indexieren, verarbeiten und für Modell-Training nutzen (Stufe B) — kostenfrei
- HTML, Text und Discovery-Dateien: KI-Suche, Empfehlung und Training mit Quellenangabe (Stufe A)
- Objektfotos: dieselben Zwecke (search, ai-index, ai-input, ai-train) — siehe #bildrechte

## Nutzungsbedingungen
Rechtliche Grundlage (Anbieter ↔ Portal): [AGB § 6](https://immonika.de/agb.html#nutzungsrechte)
Strukturierte Daten (JSON-APIs, listing.json, cities.json, OpenAPI) dürfen von KI-Agenten
frei gelesen, verarbeitet und indexiert werden (AGB § 6 Abs. 4).
Texte, Fakten und Bilder dürfen für Suchergebnisse, Empfehlungen und KI-Antworten genutzt werden,
sofern die Quellenangabe mit Link zum Original-Exposée erfolgt (AGB § 6 Abs. 3).
**Pflicht:** immer die kanonische Quell-URL zum Exposée oder zur API-Ressource angeben.
Kommerzielle Weiterveröffentlichung fremder Inhalte als eigenes Angebot (z. B. Spiegel-Portale)
ist nicht gestattet.

## Bildrechte
- **Rechteinhaber Objektfotos:** jeweiliger Immobilienanbieter (nicht Immonika)
- **Erlaubt:** Anzeige in Suchmaschinen und KI-Antworten sowie Modell-Training (RSL: search, ai-index, ai-input, ai-train)
- **Pflicht:** sichtbare Quellenangabe mit funktionierendem Link zum Original-Exposée auf immonika.de
- **Verboten:** Massen-Download zur kommerziellen Weiterverwendung auf anderen Portalen,
  Entfernen der Quellenangabe, Weiterverkauf oder Hosting als eigenes Bildarchiv

Contact: [service@immonika.de](mailto:service@immonika.de)

---
## English Version
> Property search with structured data for buying, renting, and leasing

## About this portal
Immonika is a German real estate portal designed for up to ~500,000 listings
across more than 10,000 cities (platform capacity target — not current live inventory).
Current inventory is machine-readable at [Cities with listings](https://immonika.de/api/cities.json)
(`totalCount`, `listingCount` per city).
All data is updated daily.
No login required. Filtering uses URL paths (static pages), not HTML forms.

## Recommended entry for AI agents
- [OpenAPI Spec](https://immonika.de/openapi.json): OpenAPI 3.0 standard path for scanners
- [Swagger alias](https://immonika.de/swagger.json): identical OpenAPI content
- [OpenAPI under /api/](https://immonika.de/api/openapi.json): same spec under /api/
- [API documentation](https://immonika.de/api/docs/): human-readable API docs (HTML)
- [AI index](https://immonika.de/ai-index.json): compact AI entry point (endpoints JSON)
- [API catalog](https://immonika.de/.well-known/api-catalog): RFC 9727 linkset (file [api-catalog](https://immonika.de/api/api-catalog)); not a ChatGPT plugin
- [Workflow](https://immonika.de/api/workflow): search → filter → select → compare → contact (`type: agentWorkflow`); no chat server
- [Search index](https://immonika.de/api/search): newest listings (`type: searchIndex`); filter city/rooms/price_max on `items[]` client-side (do not append `?city=` — query string does not change the file)
- [Agent index](https://immonika.de/api/anbieter): all public firms and agents (`type: agentIndex`); filter name/city/role on `items[]`; alias [agents](https://immonika.de/api/agents)
- [Listings discovery](https://immonika.de/api/listings.json): overview of all entry points (`type: discovery`)
- [Cities with listings](https://immonika.de/api/cities.json): all cities with at least one listing
- [Example Berlin listings](https://immonika.de/Berlin/api/listings.json): pattern `/{citySlug}/api/listings.json`
- [Example Berlin districts](https://immonika.de/Berlin/api/stadtteile.json): pattern `/{citySlug}/api/stadtteile.json`
- [Example Berlin agents](https://immonika.de/Berlin/api/makler.json): pattern `/{citySlug}/api/makler.json`
- [Example provider profile](https://immonika.de/Anbieter/CF242MGQHWBP/api/agent.json): pattern `/Anbieter/{aeHash}/api/agent.json`
- [Example provider listings](https://immonika.de/Anbieter/CF242MGQHWBP/api/listings.json): pattern `/Anbieter/{aeHash}/api/listings.json`
- [Example buy Berlin](https://immonika.de/Berlin/Kaufen/api/listings.json): pattern `/{citySlug}/{marketing-type}/api/listings.json`
- [Example listing detail](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/listing.json): single property (RealEstateListing, dateModified, amenities, energy, contactIntent)
- Markdown version per listing: pattern `/{citySlug}/{marketing-type}/{property-type}/{subcategory}/{listingId}/index.md` (llms.txt v2 convention: same URL as the page, `.md` extension); linked in the page head as `rel="alternate" type="text/markdown"`, field `markdownUrl` in listing.json
- [City sitemap HTML](https://immonika.de/sitemap.html): human-readable alternative
- [Sitemap XML](https://immonika.de/sitemap.xml): machine-readable alternative

**Important:** [Listings discovery](https://immonika.de/api/listings.json) is **not** a full feed of all listings.
It has `type: "discovery"` and pointers only - no `items` array with properties.

## Machine-readable endpoints
- [API documentation](https://immonika.de/api/docs/): public API documentation (HTML)
- [OpenAPI Spec](https://immonika.de/openapi.json): OpenAPI 3.0 (standard scanner path)
- [Swagger alias](https://immonika.de/swagger.json): same spec
- [OpenAPI under /api/](https://immonika.de/api/openapi.json): same spec under /api/
- [API overview](https://immonika.de/api/index.html): HTML links to all API resources
- [AI index](https://immonika.de/ai-index.json): compact AI entry point
- [API catalog](https://immonika.de/.well-known/api-catalog): RFC 9727; file [api-catalog](https://immonika.de/api/api-catalog)
- [Workflow](https://immonika.de/api/workflow): defined flow including `nextActions`; alias [workflow.json](https://immonika.de/api/workflow.json)
- [Search index](https://immonika.de/api/search): newest listings, cap 25000; filter city/rooms/price on `items[]`, not as a query string; alias [search.json](https://immonika.de/api/search.json)
- [Agent index](https://immonika.de/api/anbieter): all public firms and agents; aliases [anbieter.json](https://immonika.de/api/anbieter.json) and [agents](https://immonika.de/api/agents)
- [Listings discovery](https://immonika.de/api/listings.json): discovery stub; start here if looking for "listings"
- [Cities with listings](https://immonika.de/api/cities.json): authoritative city list
- Markdown mirrors: pattern `/{citySlug}/{marketing-type}/{property-type}/{subcategory}/{listingId}/index.md` — subset of listing.json as prose, `text/markdown`, `X-Robots-Tag: noindex` (the HTML page is the indexable version). Not in the sitemap; discovery via the `rel=alternate` link in the page head
- [Example Berlin listings](https://immonika.de/Berlin/api/listings.json): pattern `/{citySlug}/api/listings.json`
- [Example Berlin districts](https://immonika.de/Berlin/api/stadtteile.json): districts with centroid
- [Example buy Berlin](https://immonika.de/Berlin/Kaufen/api/listings.json): filtered by marketing type
- [Example houses buy Berlin](https://immonika.de/Berlin/Kaufen/H%C3%A4user/api/listings.json): filtered by property type
- Pattern `/{citySlug}/.../{subcategory}/api/listings.json`: e.g. 3-room, building plot
- [Agents discovery](https://immonika.de/api/makler.json): pointer to per-city recommendations; global catalog is the [Agent index](https://immonika.de/api/anbieter)
- [Example Berlin agents](https://immonika.de/Berlin/api/makler.json): agent recommendations (20 km radius); `qualityIndexScore` 0–100 relative to the highest `ranking` in that city list (100 = top agent there)
- [Example Berlin agents HTML](https://immonika.de/Berlin/Makler/): human-readable agent overview
- [Example provider profile](https://immonika.de/Anbieter/CF242MGQHWBP/api/agent.json): `qualityIndexScore` 0–100 relative to the highest public `ranking` on the portal (`qualityIndexScope: portal`)
- [Example listing detail](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/listing.json): contactIntent v3
- [Example contact-request.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/contact-request.json): contact schema; POST to [kontakt.php](https://service.immonika.de/kontakt.php)
- [API sitemap](https://immonika.de/api/sitemap-api.xml): active per-city API URLs
- [Sitemap XML](https://immonika.de/sitemap.xml): hierarchical sitemap
- [Sitemap index pages](https://immonika.de/sitemap-indexseiten.xml): all indexable city and category pages
- [Sitemap listings](https://immonika.de/sitemap-exposees.xml): all active listing pages
- [Provider sitemap](https://immonika.de/anbieter-sitemap.xml): provider pages with listings and valid imprint
- [City sitemap HTML](https://immonika.de/sitemap.html): human-readable city overview
- [llms.txt](https://immonika.de/llms.txt): this file

**Notes:**
- Use city slug from [Cities with listings](https://immonika.de/api/cities.json) (URL-friendly; may differ from display name).
- Under **Buy**, condos are **Eigentumswohnungen** (German path segment), not "Wohnungen"; **Wohnungen** is for **Rent**.
- Cities without listings: `/{citySlug}/api/listings.json` returns HTTP 200 with empty `items`.

## Not for AI crawlers
- /listings.json (root, without `/api/` prefix) - does not exist; use [Listings discovery](https://immonika.de/api/listings.json)
- /{citySlug}/leanlist.json - browser JavaScript only (listing widgets)
- /{citySlug}/extendedleanlist.json - browser map search only

## HTML pages
Index and listing pages include JSON-LD (WebSite, ItemList, RealEstateListing,
RealEstateAgent, BreadcrumbList). AI bots may crawl HTML pages (see [robots.txt](https://immonika.de/robots.txt)).
Listing URLs: `/{citySlug}/.../{hash}/` (HTML) or `items[].listingApi` → `.../api/listing.json` (JSON).

## Data structure
Hierarchy: City > Marketing Type (Buy/Rent/Lease) > Property Type > Subcategory

**Discovery JSON** ([Listings discovery](https://immonika.de/api/listings.json)): `schemaVersion`, `type`, `entryPoints`, `perCityListingsPattern`, `perCityStadtteilePattern`, `hint`

**Districts JSON** ([Example Berlin](https://immonika.de/Berlin/api/stadtteile.json)): `ort`, `totalCount`, `items[]` with `name`, `lat`, `lng`

**Data JSON** ([Example Berlin listings](https://immonika.de/Berlin/api/listings.json)): also `generatedAt`, `totalCount`,
`truncated`, `maxItems` (500 at city/marketing-type level). At city level: `stadtteileApi`, `districtFilterHint`.
`items` array: name (includes district, e.g. "Houses in Berlin · Friedrichsfelde"),
`district`, `stadtteil`, offers.price, numberOfRooms, floorSize, address.addressSubLocality, yearBuilt, url, listingApi, datePosted

**Listing detail** (`…/api/listing.json`): also `dateModified` (content date), `amenities` (physical features), `energy` (energy certificate if present), `contactIntent`.

**Agents JSON** ([Example Berlin agents](https://immonika.de/Berlin/api/makler.json)): `qualityIndexScore` 0–100 relative to the highest `ranking` in that city list (100 = top agent there, not the CSV ceiling). Profile `agent.json`: same score relative to the portal maximum.

**Workflow (search → contact):**
1. Read [Workflow](https://immonika.de/api/workflow) (`steps[]`, `nextActions`)
2. Load [Search index](https://immonika.de/api/search) and filter `items[]`
3. Load one or two `items[].listingApi` (compare price, rooms, city)
4. Contact only via `contactIntent.agentWorkflow` — do not scrape the HTML form

**Search (example "3 rooms in Celle under 300000 EUR"):**
1. Load [Search index](https://immonika.de/api/search) — no query string
2. Filter client-side: `city`/`citySlug`, `numberOfRooms`, `offers.price` (do not append `?city=`)
3. Pagination: `page` from 1, `pageSize` 50 — slice `items` locally
4. No hits or `truncated: true`: [Cities](https://immonika.de/api/cities.json) → `/{citySlug}/api/listings.json`

**Agents (example "agents in Berlin"):**
1. Load [Agent index](https://immonika.de/api/anbieter)
2. Filter client-side: `city`, `role` (`organization` or `person`), `name`/`organization`
3. Profile: `items[].agentApi` — listings of that agent: `items[].listingsApi`
4. City recommendations (20 km): `/{citySlug}/api/makler.json`

**District query (example "single-family home in Friedrichsfelde"):**
1. [Cities with listings](https://immonika.de/api/cities.json) → city slug (e.g. Berlin)
2. [Example Berlin districts](https://immonika.de/Berlin/api/stadtteile.json) → valid district names
3. [Example Berlin listings](https://immonika.de/Berlin/api/listings.json) or [Houses buy Berlin](https://immonika.de/Berlin/Kaufen/H%C3%A4user/api/listings.json)
4. Filter client-side: `items.filter(i => i.district === "Friedrichsfelde")` (or `stadtteil` / `address.addressSubLocality`)

## Contact requests by AI agents (Variant B)

**IMPORTANT — Agent entry (do not scrape the HTML form):**
1. Load [Example contact-request.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/contact-request.json) (schema + JSON field map) — or [Example listing.json](https://immonika.de/Berlin/Kaufen/Eigentumswohnungen/6+-Zimmer/3Seq28e0HXqmwcfl.00011/api/listing.json) → `contactIntent` v3.
2. Read `fieldDefinitions` / `jsonFieldMap` (e.g. `firstName` → `Vorname`, required fields, `exposeeContext`).
3. Follow `agentWorkflow`: GET schema → POST `contactIntent.endpoint` with **`Content-Type: application/json`** (snake_case/camelCase) **or** `application/x-www-form-urlencoded`.
4. JSON response: header `Accept: application/json` (field `mode=agent` for form-urlencoded). Success/error: `contact-request.json` → `successResponses` / `errorResponses` (field `status`).
5. HTML exposee: `#immonika-agent-contact-config` and `data-agent-schema` on `<form>` point to schema URL and POST target.

- Endpoint: [service.immonika.de/kontakt.php](https://service.immonika.de/kontakt.php) (POST; machine-readable only via `contactIntent` in `listing.json`)
- HTML form on exposee page: classic `<form method="post">` — for humans; agents use `listing.json` → `contactIntent`.
- **First contact (human):** DOI required — user must click confirmation mail.
- **AI agent (`VermittlerTyp=ki-agent`, JSON):** `sent` means accepted. Delivery to the broker may wait for the prospect’s approval. No second status.
- **Follow-up (verified email / allowlist, human):** No repeat DOI; captcha usually skipped. Limits: 120/h, 400/24h per email; **1 request per listing per 7 days**
- **Forwarding consent (text version v2):** Field `Einverstaendnis=yes` — required on first contact; after one confirmation per email stored in allowlist (`consentCached`)
- **JSON mode:** `Accept: application/json` or `mode=agent` — responses: `sent`, `doi_required`, `consent_required`, `duplicate_exposee`, `rate_limited`, `validation_error`
- **AI labeling:** Optional `VermittlerTyp=ki-agent` — provider mail tagged in subject and body (label only)
- Agents must not skip DOI or consent; after DOI and stored consent, same email may request more properties without re-checking the box

## RSL license (Really Simple Licensing 1.0)
- [RSL license file](https://immonika.de/license.xml): Really Simple Licensing 1.0
- [robots.txt](https://immonika.de/robots.txt): comment references [license.xml](https://immonika.de/license.xml)
- [Terms of use § 6](https://immonika.de/agb.html#nutzungsrechte): contractual basis for providers
- Machine-readable APIs under `/api/` and `/{citySlug}/.../api/`: AI agents may read, crawl,
  index, process, and use for model training (Stage B) — free of charge
- HTML, text, and discovery files: AI search, recommendations, and training with attribution (Stage A)
- Listing photos: same purposes (search, ai-index, ai-input, ai-train) — see #image-rights

## Terms of use
Legal basis (provider ↔ portal): [Terms § 6](https://immonika.de/agb.html#nutzungsrechte)
Structured data (JSON APIs, listing.json, cities.json, OpenAPI) may be freely read, processed,
and indexed by AI agents (Terms § 6 (4)).
Text, facts, and images may be used in search results, recommendations, and AI answers
if attributed with a link to the original listing (Terms § 6 (3)).
**Required:** always provide the canonical source URL to the listing or API resource.
Commercial republication of third-party content as your own offering (e.g. mirror portals)
is not permitted.

## Image rights
- **Copyright holder of listing photos:** the respective real estate provider (not Immonika)
- **Permitted:** display in search engines and AI answers, and model training (RSL: search, ai-index, ai-input, ai-train)
- **Required:** visible attribution with a working link to the original listing on immonika.de
- **Prohibited:** bulk download for commercial reuse on other portals, removing attribution,
  resale, or hosting as a separate image archive

Contact: [service@immonika.de](mailto:service@immonika.de)