{
  "openapi": "3.0.3",
  "info": {
    "title": "immonika Listings API",
    "version": "1.0",
    "description": "Oeffentliche, read-only Listings-API als statische JSON-Dateien. Kein API-Key. OpenAPI-Standardpfade: https://immonika.de/openapi.json und https://immonika.de/swagger.json. Einstieg: /api/listings.json, /api/cities.json, pro Ort /{ortSlug}/api/listings.json. Doku: https://immonika.de/api/docs/",
    "termsOfService": "https://immonika.de/agb.html",
    "contact": {
      "url": "https://immonika.de/info.html"
    }
  },
  "externalDocs": {
    "description": "Menschenlesbare API-Dokumentation (DE)",
    "url": "https://immonika.de/api/docs/"
  },
  "servers": [
    { "url": "https://immonika.de" }
  ],
  "tags": [
    { "name": "discovery", "description": "Einstieg und Verweise" },
    { "name": "cities", "description": "Orte mit mindestens einem Inserat" },
    { "name": "listings", "description": "Inserate pro Ort oder Filter-Pfad" }
  ],
  "paths": {
    "/api/listings.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "API-Discovery (kein Gesamt-Feed)",
        "description": "Liefert type=discovery mit Verweisen auf cities.json, ai-index.json und llms.txt. Enthaelt keine items-Liste mit Exposees.",
        "operationId": "getListingsDiscovery",
        "responses": {
          "200": {
            "description": "Discovery-Stub",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DiscoveryResponse" }
              }
            }
          }
        }
      }
    }
,
    "/api/cities.json": {
      "get": {
        "tags": ["cities"],
        "summary": "Alle Orte mit Inseraten",
        "description": "Authoritative Liste aktiver Orte inkl. listingCount und Ziel-URL fuer Ort-Listings.",
        "operationId": "getCities",
        "responses": {
          "200": {
            "description": "Stadtliste",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CitiesResponse" }
              }
            }
          }
        }
      }
    }
,
    "/{ortSlug}/api/listings.json": {
      "get": {
        "tags": ["listings"],
        "summary": "Inserate eines Ortes",
        "description": "Schema.org RealEstateListing in items. maxItems 500 auf Ort- und Vermarktungsart-Ebene.",
        "operationId": "getListingsByCity",
        "parameters": [
          {
            "name": "ortSlug",
            "in": "path",
            "required": true,
            "description": "URL-Slug aus /api/cities.json (Feld url)",
            "schema": { "type": "string", "example": "Berlin" }
          }
        ],
        "responses": {
          "200": {
            "description": "Listings oder leeres items bei Ort ohne Inserate",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ListingsResponse" }
              }
            }
          }
        }
      }
    }
,
    "/{ortSlug}/{vermarktungsart}/api/listings.json": {
      "get": {
        "tags": ["listings"],
        "summary": "Gefilterte Inserate (Vermarktungsart)",
        "description": "vermarktungsart: Kaufen, Mieten oder Pachten. Weitere Ebenen: /{objektart}/api/listings.json und /{unterkategorie}/api/listings.json.",
        "operationId": "getListingsByCityAndMarketing",
        "parameters": [
          { "name": "ortSlug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "vermarktungsart", "in": "path", "required": true, "schema": { "type": "string", "enum": ["Kaufen", "Mieten", "Pachten"] } }
        ],
        "responses": {
          "200": {
            "description": "Gefilterte Listings",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ListingsResponse" }
              }
            }
          }
        }
      }
    }
,
    "/api/openapi.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "Diese OpenAPI-Spezifikation",
        "operationId": "getOpenApiSpec",
        "responses": {
          "200": {
            "description": "OpenAPI 3.0 JSON",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DiscoveryResponse": {
        "type": "object",
        "required": ["schemaVersion", "type", "entryPoints"],
        "properties": {
          "schemaVersion": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "type": { "type": "string", "enum": ["discovery"] },
          "description": { "type": "string" },
          "entryPoints": { "type": "object" },
          "perCityListingsPattern": { "type": "string" },
          "hint": { "type": "string" }
        }
      },
      "CitiesResponse": {
        "type": "object",
        "required": ["schemaVersion", "totalCount", "items"],
        "properties": {
          "schemaVersion": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "totalCount": { "type": "integer" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CityItem" }
          }
        }
      },
      "CityItem": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "postalCode": { "type": "string" },
          "listingCount": { "type": "integer" },
          "url": { "type": "string", "description": "Relativer Pfad zu Ort-Listings" }
        }
      },
      "ListingsResponse": {
        "type": "object",
        "required": ["schemaVersion", "totalCount", "items"],
        "properties": {
          "schemaVersion": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "totalCount": { "type": "integer" },
          "truncated": { "type": "boolean" },
          "maxItems": { "type": "integer" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/RealEstateListing" }
          }
        }
      },
      "RealEstateListing": {
        "type": "object",
        "properties": {
          "@type": { "type": "string", "example": "RealEstateListing" },
          "name": { "type": "string" },
          "url": { "type": "string" },
          "offers": {
            "type": "object",
            "properties": {
              "@type": { "type": "string" },
              "price": { "type": "number" },
              "priceCurrency": { "type": "string" },
              "availability": { "type": "string" }
            }
          },
          "numberOfRooms": { "type": "number" },
          "floorSize": { "type": "object" },
          "yearBuilt": { "type": "integer" },
          "datePosted": { "type": "string", "format": "date" },
          "address": { "type": "object" }
        }
      }
    }
  }
}