{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/immokit-ai/json-schema/immokit-ai-bodenrichtwert-response-schema.json",
  "title": "BodenrichtwertResponse",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immokit-ai-openapi.json#/components/schemas/BodenrichtwertResponse",
  "type": "object",
  "properties": {
    "address_input": {
      "type": "string",
      "description": "The original address you provided"
    },
    "address_resolved": {
      "type": "string",
      "description": "The geocoded, normalized address"
    },
    "coordinates": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude (WGS84)"
        },
        "lon": {
          "type": "number",
          "description": "Longitude (WGS84)"
        }
      }
    },
    "bodenrichtwerte": {
      "type": "array",
      "description": "List of land values at this location (may contain multiple entries for different land use types)",
      "items": {
        "$ref": "#/$defs/Bodenrichtwert"
      }
    },
    "cache_hit": {
      "type": "boolean",
      "description": "Whether the result was served from cache"
    },
    "cache_stale": {
      "type": "boolean",
      "description": "Present (and always `true`) only when the value was served from the cache's\nemergency window: it could not be re-checked against the official source just\nnow, so the last known value was returned instead of an error. A background\nrefresh is triggered, so a later request for the same coordinate normally\nanswers fresh again. The field is omitted entirely when the value was fresh.\n\nThis is not a correctness warning. Bodenrichtwerte are published for an annual\nStichtag, and the `stichtag` on every entry remains the authoritative reference\nfor what point in time the value applies to.\n"
    },
    "attribution": {
      "$ref": "#/$defs/Attribution"
    },
    "quelle": {
      "type": "array",
      "description": "Every source whose data is in this response, each with its licence. Two entries:\nthe Gutachterausschuss data for the land value, and the BKG address service that\nresolved the address into the coordinate the value was looked up at. Both are\nlicensed dl-de/by-2-0 and both must stay visible when you pass the data on —\n`attribution` names only the first of them.\n",
      "items": {
        "$ref": "#/$defs/Quelle"
      }
    },
    "disclaimer": {
      "type": "string",
      "description": "Pflicht-Hinweis, dass der Bodenrichtwert ein gutachterlicher Orientierungswert ist —\nkein Verkehrswert, kein Verkaufspreis, keine Rechtsberatung. Muss bei Weitergabe sichtbar bleiben.\n"
    }
  },
  "$defs": {
    "Attribution": {
      "type": "object",
      "description": "Required attribution for the data source (dl-de/by-2-0 license)",
      "properties": {
        "text": {
          "type": "string"
        },
        "license_url": {
          "type": "string",
          "format": "uri"
        },
        "year": {
          "type": "integer"
        }
      }
    },
    "Bodenrichtwert": {
      "type": "object",
      "properties": {
        "nutzungsart": {
          "type": "string",
          "description": "Human-readable land use type in German (e.g. Wohnbaufläche, Gewerbliche Baufläche)"
        },
        "code": {
          "type": "string",
          "enum": [
            "W",
            "M",
            "G",
            "S",
            "L",
            "F",
            "SO"
          ],
          "description": "Short code for the official land-use category: W=residential, M=mixed, G=commercial, S=special, L=agricultural, F=forestry, SO=other"
        },
        "brw_euro_pro_m2": {
          "type": "number",
          "description": "Land value in EUR per square meter"
        },
        "stichtag": {
          "type": "string",
          "format": "date",
          "description": "Reference date of the land value assessment (ISO 8601, YYYY-MM-DD)"
        },
        "gemeinde": {
          "type": "string",
          "description": "Municipality name"
        },
        "gutachterausschuss": {
          "type": "string",
          "description": "Name of the expert committee (Gutachterausschuss) that issued the value.\nMay be an empty string in some federal states where the official source does not\npublish the committee name in its feed (only the numeric committee ID).\n"
        },
        "bodenrichtwertnummer": {
          "type": "string",
          "description": "Unique identifier of the BRW zone within its Gutachterausschuss. Use this\nwhen referencing a specific zone in a formal appraisal — the value is\nstable across requests for the same coordinate.\n"
        },
        "zonenbezeichnung": {
          "type": "string",
          "description": "Human-readable name of the BRW zone — often a district or quarter\nname (e.g. \"Regierungsviertel\" for the government quarter in Hannover),\noptionally combined with the land use code (e.g. \"Stederdorf W\" for the\nWohnbau zone in the Stederdorf district).\n"
        },
        "bauweise": {
          "type": "string",
          "description": "Permitted building configuration as published in the land development plan\n(e.g. \"offen\" = detached, \"geschlossen\" = attached). Often unset.\n"
        },
        "geschossflaechenzahl": {
          "type": "number",
          "description": "Floor Area Ratio (GFZ) permitted in the zone — the ratio of total gross\nfloor area to plot area. Input for the price conversion if the subject\nplot has a different FAR than the one the BRW was calibrated for.\n"
        },
        "grundflaechenzahl": {
          "type": "number",
          "description": "Site Coverage Ratio (GRZ) — the ratio of built-over area to plot area.\n"
        },
        "vollgeschosszahl": {
          "type": "number",
          "description": "Number of full storeys (VGZ) permitted in the zone."
        },
        "baumassenzahl": {
          "type": "number",
          "description": "Building Mass Ratio (BMZ) — gross building volume per plot area. Used\nprimarily in dense commercial / high-rise zones instead of GFZ.\n"
        },
        "wertrel_geschossflaechenzahl": {
          "type": "number",
          "description": "Reference Floor Area Ratio (\"wertrelevante GFZ\", WGF) — the GFZ the\nexpert committee used as the basis for this Bodenrichtwert. If the\nsubject plot has a different GFZ, the BRW must be re-indexed against\nthe committee's published conversion table. Without this field a\nprofessional appraisal cannot adjust the value accurately.\n"
        }
      }
    },
    "Quelle": {
      "type": "object",
      "description": "One source with its licence. The wording in `provider` is prescribed — do not\nparaphrase it when displaying or forwarding the data.\n",
      "properties": {
        "provider": {
          "type": "string",
          "description": "Verbatim source notice, e.g. \"© GeoBasis-DE/BKG\""
        },
        "lizenz": {
          "type": "string",
          "description": "Licence identifier, e.g. dl-de/by-2-0"
        },
        "lizenz_url": {
          "type": "string",
          "format": "uri"
        },
        "quelle_url": {
          "type": "string",
          "format": "uri",
          "description": "Human-readable source page — not the service endpoint"
        },
        "stand": {
          "type": "string",
          "description": "Vintage of the data, where the source publishes one"
        }
      }
    }
  }
}