# Immonika - Deutsches Immobilienportal
> Immobiliensuche mit strukturierten Daten fuer Kauf, Miete und Pacht

## Ueber dieses Portal
Immonika ist ein deutsches Immobilienportal ausgelegt fuer ca. ~500.000 Inserate
in ueber 10.000 Orten. Alle Daten werden taeglich aktualisiert.
Kein Login noetig. Filter erfolgen ueber URL-Pfade (statische Seiten), nicht ueber Formulare.

## Empfohlener Einstieg fuer KI-Agenten
1. `/openapi.json` oder `/swagger.json` (OpenAPI 3.0 Standardpfade) - alternativ `/api/openapi.json`
2. `/api/docs/` (menschenlesbare API-Doku)
3. `/ai-index.json` oder `/api/listings.json` (Discovery) - Uebersicht aller Einstiegspunkte
4. `/api/cities.json` - alle Orte mit mindestens einem Inserat (`listingCount`, `url` pro Ort)
5. `/{ortSlug}/api/listings.json` - Inserate eines Ortes (echte Daten, Schema.org; Stadtteil in `district`, `stadtteil`, `name`)
6. `/{ortSlug}/api/stadtteile.json` - Bezirke/Stadtteile des Ortes (Centroid lat/lng; Filterwerte fuer listings.json)
7. `/{ortSlug}/api/makler.json` - empfohlene Makler im Ort/Umkreis (RealEstateAgent; parallel zu listings.json)
8. `/Anbieter/{aeHash}/api/agent.json` - Maklerprofil (RealEstateAgent, ranking, listingCount)
9. `/Anbieter/{aeHash}/api/listings.json` - Inserate dieses Anbieters (inkl. Stadtteil wie Ort-API)
10. `/Anbieter/{aeHash}/{meHash}/api/agent.json` - Makler-Personenprofil (mit parentOrganization)
11. Bei Bedarf tiefer: `/{ortSlug}/{vermarktungsart}/api/listings.json` usw.
12. Exposee-Detail: `/{ortSlug}/{vermarktungsart}/{objektart}/{unterkategorie}/{exposeeId}/api/listing.json` — Einzelobjekt (RealEstateListing, contactIntent, parentFeed)
13. HTML-Alternative: `/sitemap.html` (menschenlesbar) oder `/sitemap.xml` (maschinenlesbar)

**Wichtig:** `/api/listings.json` ist **kein** Gesamt-Feed aller Inserate.
Es enthaelt `type: "discovery"` und Verweise - keine `items`-Liste mit Exposees.

## Maschinenlesbare Endpunkte
- /api/docs/ - oeffentliche API-Dokumentation (HTML, DE)
- /openapi.json - OpenAPI 3.0 (Standardpfad fuer Scanner)
- /swagger.json - identischer OpenAPI-Inhalt (Swagger-Alias)
- /api/openapi.json - gleiche Spec unter /api/
- /api/index.html - API-Uebersicht (Links)
- /ai-index.json - kompakter KI-Einstieg (Endpoints-JSON: llms, Sitemaps, API-Root)
- /api/listings.json - Discovery-Stub (`type: discovery`; Start hier, wenn "listings" gesucht wird)
- /api/cities.json - authoritative Ortliste mit Inseraten (`listingCount`, Ziel-URL pro Ort)
- /{ortSlug}/api/listings.json - alle Inserate eines Ortes (Schema.org RealEstateListing, Feld `items`; Stadtteil in `district`, `stadtteil`, `address.addressSubLocality`, `name`)
- /{ortSlug}/api/stadtteile.json - Stadtteile/Bezirke mit Centroid (`items[].name`, `lat`, `lng`)
- /{ortSlug}/{vermarktungsart}/api/listings.json - gefiltert: Kaufen, Mieten, Pachten
- /{ortSlug}/{vermarktungsart}/{objektart}/api/listings.json - z. B. Eigentumswohnungen, Haeuser, Gewerbe
- /{ortSlug}/.../{unterkategorie}/api/listings.json - z. B. 3-Zimmer, Baugrund
- /api/makler.json - Discovery-Stub fuer Makler-API (Verweis auf Ort-Pattern)
- /{ortSlug}/api/makler.json - Makler-Empfehlungen fuer einen Ort (20 km Umkreis, Feld items mit ranking)
- /{ortSlug}/Makler/api/makler.json - identischer Inhalt (Kontext Orts-Anbieterseite)
- /{ortSlug}/Makler/ - menschenlesbare Makler-Uebersicht (HTML)
- /Anbieter/{aeHash}/api/agent.json - Anbieterprofil (Schema.org RealEstateAgent)
- /Anbieter/{aeHash}/api/listings.json - Inserate des Anbieters (mit `district`/`stadtteil`/`address`)
- /Anbieter/{aeHash}/{meHash}/api/agent.json - Makler-Personenprofil
- /Anbieter/{aeHash}/{meHash}/api/listings.json - Inserate des Maklers
- /{ortSlug}/{vermarktungsart}/{objektart}/{unterkategorie}/{exposeeId}/api/listing.json - Exposee-Detail (contactIntent v3, fieldDefinitions, agentWorkflow)
- /{ortSlug}/.../{exposeeId}/api/contact-request.json - Kontakt-Schema + JSON-POST-Mapping (GET); POST an service.immonika.de/kontakt.php
- /api/sitemap-api.xml - Sitemap aller aktiven Orts-API-URLs (Listings + Makler; keine Einzel-Exposees)
- /sitemap.xml - hierarchische Sitemap aller Index- und Exposee-Seiten
- /sitemap.html - menschenlesbare Ortsuebersicht (Bundesland, Landkreis, Orte)
- /llms.txt - diese Datei

**Hinweise:**
- `ortSlug` aus `/api/cities.json` verwenden (URL-freundlich, kann von Schreibweise des Ortsnamens abweichen).
- Unter **Kaufen** heisst die Objektart **Eigentumswohnungen** (nicht "Wohnungen"); **Wohnungen** gilt bei **Mieten**.
- Orte ohne Inserate: `/{ortSlug}/api/listings.json` liefert HTTP 200 mit leerem `items`-Array.

## Nicht fuer KI-Crawler
- /listings.json (ohne `/api/`-Prefix im Root) - existiert nicht; nutze `/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 duerfen HTML-Seiten crawlen (siehe robots.txt).
Exposee-URLs: `/{ortSlug}/.../{hash}/` (HTML) bzw. `.../api/listing.json` (JSON; aus Listings-Feld `url` + `/api/listing.json` oder Sitemap).

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

**Discovery-JSON** (`/api/listings.json`): `schemaVersion`, `type`, `entryPoints`, `perCityListingsPattern`, `perCityStadtteilePattern`, `hint`

**Stadtteile-JSON** (`/{ortSlug}/api/stadtteile.json`): `ort`, `totalCount`, `items[]` mit `name`, `lat`, `lng`

**Daten-JSON** (`/{ortSlug}/.../api/listings.json`): zusaetzlich `generatedAt`, `totalCount`,
`truncated`, `maxItems` (500 auf Ort- und Vermarktungsart-Ebene). Auf Ortsebene: `stadtteileApi`, `districtFilterHint`.
Array `items` mit RealEstateListing-Feldern: name (inkl. Bezirk, z. B. „Haeuser in Berlin · Friedrichsfelde"),
`district`, `stadtteil`, offers.price, numberOfRooms, floorSize, address.addressSubLocality, yearBuilt, url, datePosted

**Stadtteil-Abfrage (Beispiel „EFH in Friedrichsfelde“):**
1. `/api/cities.json` → `ortSlug` (z. B. Berlin)
2. `/{ortSlug}/api/stadtteile.json` → gueltige Bezirksnamen (`items[].name`)
3. `/{ortSlug}/api/listings.json` oder `/{ortSlug}/Kaufen/Haeuser/api/listings.json`
4. Clientseitig filtern: `items.filter(i => i.district === "Friedrichsfelde")` (oder `stadtteil` / `address.addressSubLocality`)

## Kontaktanfragen durch KI-Agenten (Variante B)

**WICHTIG — Einstieg fuer Agenten (nicht das HTML-Formular scrapen):**
1. `.../api/contact-request.json` laden (Schema + JSON-Feld-Mapping) — oder `.../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: `https://service.immonika.de/kontakt.php` (POST; Maschinenlesbar nur ueber `contactIntent` in `listing.json`)
- HTML-Formular auf der Exposée-Seite: klassisches `<form method="post">` — nur fuer Menschen; Agenten nutzen `listing.json` → `contactIntent`.
- **Erstkontakt (neue E-Mail):** DOI-Pflicht — Nutzer muss Bestaetigungsmail klicken (`humanStepsRequired: email_doi_confirmation`). Kein DOI-Bypass.
- **Folgekontakt (verifizierte E-Mail / Allowlist):** Kein erneutes DOI; Captcha entfaellt 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 Bestaetigung 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 duerfen DOI und Einwilligung nicht umgehen; nach DOI und gespeicherter Einwilligung duerfen sie fuer dieselbe E-Mail weitere Objekte ohne erneute Checkbox anfragen

## Nutzungsbedingungen
Daten duerfen fuer Suchergebnisse und Empfehlungen zitiert werden.
Bitte immer die Quell-URL zum Exposee angeben.
Scraping der Bilder aus Exposees nicht zulaessig (Denn Urheberrecht liegt bei den Anbietern, nicht immonika.de)

Contact: service@immonika.de

---
# Immonika - German Real Estate Portal (English Version)
> Property search with structured data for buying, renting, and leasing

## About this portal
Immonika is a German real estate portal designed for ~500,000 listings
across over all 10,000 cities. All data is updated daily.
No login required. Filtering uses URL paths (static pages), not HTML forms.

## Recommended entry for AI agents
1. `/openapi.json` or `/swagger.json` (OpenAPI 3.0 standard paths) - also `/api/openapi.json`
2. `/api/docs/` (human API docs)
3. `/ai-index.json` or `/api/listings.json` (discovery) - overview of all entry points
4. `/api/cities.json` - all cities with at least one listing (`listingCount`, `url` per city)
5. `/{citySlug}/api/listings.json` - listings for one city (Schema.org; district in `district`, `stadtteil`, `name`)
6. `/{citySlug}/api/stadtteile.json` - districts/neighborhoods with centroid (filter values for listings)
7. `/{citySlug}/api/makler.json` - recommended agents in city/area (RealEstateAgent; parallel to listings.json)
8. If needed, go deeper: `/{citySlug}/{marketing-type}/api/listings.json`, etc.
9. Listing detail: `/{citySlug}/{marketing-type}/{property-type}/{subcategory}/{exposeeId}/api/listing.json` — single property (RealEstateListing, contactIntent, parentFeed)
10. HTML alternative: `/sitemap.html` (human-readable) or `/sitemap.xml` (machine-readable)

**Important:** `/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/docs/ - public API documentation (HTML)
- /openapi.json - OpenAPI 3.0 (standard scanner path)
- /swagger.json - same spec (Swagger alias)
- /api/openapi.json - same spec under /api/
- /api/index.html - API overview page
- /ai-index.json - compact AI entry point (endpoints JSON: llms, sitemaps, API root)
- /api/listings.json - discovery stub (`type: discovery`; start here if looking for "listings")
- /api/cities.json - authoritative city list with listings (`listingCount`, target URL per city)
- /{citySlug}/api/listings.json - all listings in a city (`items`; district in `district`, `stadtteil`, `address.addressSubLocality`, `name`)
- /{citySlug}/api/stadtteile.json - districts with centroid (`items[].name`, `lat`, `lng`)
- /{citySlug}/{marketing-type}/api/listings.json - filtered: Buy, Rent, Lease
- /{citySlug}/{marketing-type}/{property-type}/api/listings.json - e.g. condos, houses, commercial
- /{citySlug}/.../{subcategory}/api/listings.json - e.g. 3-room, building plot
- /api/makler.json - discovery stub for agent API
- /{citySlug}/api/makler.json - agent recommendations per city (20 km radius, ranking field)
- /{citySlug}/Makler/api/makler.json - same content (OA page context)
- /{citySlug}/Makler/ - human-readable agent overview (HTML)
- /{citySlug}/.../{exposeeId}/api/listing.json - listing detail (contactIntent v3)
- /{citySlug}/.../{exposeeId}/api/contact-request.json - contact schema + JSON POST mapping (GET); POST to service.immonika.de/kontakt.php
- /api/sitemap-api.xml - sitemap of active per-city API URLs (listings + agents; no per-listing exposee URLs)
- /sitemap.xml - hierarchical sitemap of all index and listing pages
- /sitemap.html - human-readable city overview (state, district, cities)
- /llms.txt - this file

**Notes:**
- Use `ortSlug` / city slug from `/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 `/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).
Listing URLs: `/{citySlug}/.../{hash}.html` (from API field `url` or sitemap).

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

**Discovery JSON** (`/api/listings.json`): `schemaVersion`, `type`, `entryPoints`, `perCityListingsPattern`, `perCityStadtteilePattern`, `hint`

**Districts JSON** (`/{citySlug}/api/stadtteile.json`): `ort`, `totalCount`, `items[]` with `name`, `lat`, `lng`

**Data JSON** (`/{citySlug}/.../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, datePosted

**District query (example "single-family home in Friedrichsfelde"):**
1. `/api/cities.json` → city slug (e.g. Berlin)
2. `/{citySlug}/api/stadtteile.json` → valid district names
3. `/{citySlug}/api/listings.json` or `/{citySlug}/Kaufen/Haeuser/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 `.../api/contact-request.json` (schema + JSON field map) — or `.../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: `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 (new email):** DOI required — user must click confirmation mail. No bypass.
- **Follow-up (verified email / allowlist):** 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

## Terms of use
Data may be cited for search results and recommendations.
Please always provide the source URL to the listing.
No scraping of images alowed.

Contact: service@immonika.de