immokit-ai Bodenwert API

openapi: 3.2.0
info:
  title: bodenrichtwert.ai Bodenwert API
  description: 'API for retrieving German land values (Bodenrichtwerte) by address.

    Provide a full German address and receive the land value in EUR per square meter,

    including the land use type, reference date, municipality, and source attribution.

    Covers all German states except Schleswig-Holstein, Sachsen, and Bayern (blocked for legal reasons, HTTP 451).'
  version: 1.2.0
  contact:
    url: https://api.bodenrichtwert.ai
servers:
- url: https://api.immokit.ai
  description: Production REST API
tags:
- name: Bodenwert
paths:
  /api/bodenwert:
    post:
      operationId: calculateBodenwert
      summary: Calculate the Bodenwert (density-adjusted land value) for a plot
      description: 'Calculates the actual land value of a plot at a building density (Geschossflächenzahl, GFZ)

        that differs from the one the official Bodenrichtwert is based on. Pure calculation — no address

        lookup, no external data-source call — and it does NOT count against your monthly request quota.


        Without `flaeche` it returns the actual Bodenrichtwert (density-adjusted, EUR/m²); with `flaeche`

        it additionally returns the Bodenwert (total plot value, EUR).


        Model: the standard German conversion-coefficient formula, used by the Gutachterausschüsse as

        the fallback when no zone-specific table is published (cf. ErbStH on § 179 BewG):

        - K(GFZ) = 0.6·√GFZ + 0.2·GFZ + 0.2 (normalized so K(1.0) = 1.0)

        - bodenrichtwert_tatsaechlich = brw × K(gfz_tatsaechlich) / K(gfz_referenz)


        The reference GFZ (`gfz_referenz`) is the density the Bodenrichtwert is calibrated for — from

        `GET /api/bodenrichtwert` it is the `wertrel_geschossflaechenzahl` field. Not every state

        publishes it (e.g. NRW exposes only the number of full storeys); then supply the reference GFZ

        from the official zone information yourself.


        Optional Vorderland/Hinterland split: pass `hinterland_flaeche_m2` (area of the rear part of the

        plot, in m², must be less than `flaeche`) together with `hinterland_faktor` (its value factor

        relative to the front part, 0 to 1) to split the Bodenwert into a front-plot and a rear-plot share

        and blend them into one total. `bodenwert_euro` stays the ONE canonical total field — it is now

        the blended value. The breakdown (`vorderland_wert_euro`, `hinterland_wert_euro`) is additional

        detail in the response; it is NOT a standard nationwide model — the split line and factor are

        supplied by the caller, not by the Gutachterausschuss (see the mandatory `hinweis` in the

        response). Both fields are required together, and require `flaeche` to be set; `hinterland_faktor`

        outside `[0, 1]` is rejected — a value above 1 would mean the rear part is worth more than the

        front, which is not a depth discount (if the rear part sits in its own Bodenrichtwert zone,

        query it separately via `GET /api/bodenrichtwert` instead).


        The result is an orienting calculation and does NOT replace the zone-specific official conversion

        table of the responsible Gutachterausschuss. It is not a market value.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - brw
              - gfz_referenz
              - gfz_tatsaechlich
              properties:
                brw:
                  type: number
                  minimum: 0
                  description: The official Bodenrichtwert to base the calculation on, in EUR per square meter.
                gfz_referenz:
                  type: number
                  exclusiveMinimum: 0
                  description: Reference GFZ the Bodenrichtwert is based on (wertrelevante GFZ, greater than 0).
                gfz_tatsaechlich:
                  type: number
                  exclusiveMinimum: 0
                  description: Actual or permitted GFZ of the subject plot (greater than 0).
                flaeche:
                  type: number
                  exclusiveMinimum: 0
                  description: Optional plot area in square meters. If given, the total Bodenwert is also returned.
                hinterland_flaeche_m2:
                  type: number
                  exclusiveMinimum: 0
                  description: 'Optional: area of the rear part of the plot (Hinterland) in square meters — must be

                    less than `flaeche`. Only together with `hinterland_faktor`; requires `flaeche`.

                    '
                hinterland_faktor:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: 'Optional: value factor of the rear plot relative to the front plot, 0 to 1 (e.g. 0.2

                    for 20% of the front Bodenrichtwert). Only together with `hinterland_flaeche_m2`. No

                    official model — supplied by the caller. Values below 0.10 or above 0.50 trigger an

                    additional note in the response; values outside [0, 1] are rejected.

                    '
            example:
              brw: 450
              gfz_referenz: 0.8
              gfz_tatsaechlich: 1.2
      security:
      - OAuth2: []
      - BearerAuth: []
      - QueryToken: []
      responses:
        '200':
          description: The density-adjusted land value (and total Bodenwert if flaeche was given)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BodenwertResponse'
              example:
                brw_input_euro_pro_m2: 450
                gfz_referenz: 0.8
                gfz_tatsaechlich: 1.2
                koeffizient_referenz: 0.8967
                koeffizient_tatsaechlich: 1.0973
                faktor: 1.2237
                bodenrichtwert_tatsaechlich_euro_pro_m2: 550.68
                modell: amtliche-standardformel
                formel: K(GFZ) = 0,6·√GFZ + 0,2·GFZ + 0,2  ·  BRW_tatsächlich = BRW × K(GFZ_ist) / K(GFZ_ref)
                disclaimer: Orientierende Umrechnung nach der Standardformel für Umrechnungskoeffizienten (0,6·√GFZ + 0,2·GFZ + 0,2; u. a. ErbStH zu § 179 BewG). Ersetzt NICHT die zonenspezifische amtliche Umrechnungstabelle des zuständigen Gutachterausschusses. Gutachterlicher Orientierungswert — kein Verkehrswert, kein Kaufpreis, keine Rechtsberatung.
        '400':
          description: 'Missing or invalid fields (malformed JSON body, non-numeric value, brw < 0, or a GFZ <= 0).

            Also covers the Vorderland/Hinterland split: `missing_parameter` when only one of

            `hinterland_flaeche_m2`/`hinterland_faktor` is set or `flaeche` is missing;

            `invalid_hinterland_flaeche_m2` when it is not > 0 or not < `flaeche`;

            `invalid_hinterland_faktor` when it is outside `[0, 1]`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: IP rate limit exceeded (120 requests/minute) — retry after the number of seconds in the Retry-After header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unexpected internal error — retry later; contact support@bodenrichtwert.ai if it persists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Bodenwert
components:
  schemas:
    BodenwertResponse:
      type: object
      properties:
        brw_input_euro_pro_m2:
          type: number
          description: The official Bodenrichtwert you provided (EUR/m²).
        gfz_referenz:
          type: number
          description: Reference GFZ the value is based on (wertrelevante GFZ).
        gfz_tatsaechlich:
          type: number
          description: Actual or permitted GFZ of the subject plot.
        koeffizient_referenz:
          type: number
          description: Conversion coefficient K(gfz_referenz) = 0.6·√GFZ + 0.2·GFZ + 0.2.
        koeffizient_tatsaechlich:
          type: number
          description: Conversion coefficient K(gfz_tatsaechlich).
        faktor:
          type: number
          description: Conversion factor K(gfz_tatsaechlich) / K(gfz_referenz).
        bodenrichtwert_tatsaechlich_euro_pro_m2:
          type: number
          description: The actual (density-adjusted) Bodenrichtwert for the plot (EUR/m²).
        grundstuecksflaeche_m2:
          type: number
          description: Plot area — present only when `flaeche` was supplied.
        bodenwert_euro:
          type: number
          description: 'The Bodenwert (total plot value) — ONE canonical total field. Present only when `flaeche` was

            supplied. Without a Vorderland/Hinterland split: bodenrichtwert_tatsaechlich × flaeche. With a

            split: vorderland_wert_euro + hinterland_wert_euro (same field, now blended).

            '
        hinterland_flaeche_m2:
          type: number
          description: Echo of the input (m²). Present only when the Vorderland/Hinterland split was used.
        hinterland_faktor:
          type: number
          description: Echo of the input (0 to 1). Present only when the Vorderland/Hinterland split was used.
        vorderland_flaeche_m2:
          type: number
          description: grundstuecksflaeche_m2 minus hinterland_flaeche_m2. Present only when the Vorderland/Hinterland split was used.
        vorderland_wert_euro:
          type: number
          description: 'Front-plot share of the total value (bodenrichtwert_tatsaechlich × vorderland_flaeche_m2).

            Present only when the Vorderland/Hinterland split was used. This breakdown is additional

            detail — the MCP tool''s text summary deliberately mentions only the ONE total, bodenwert_euro.

            '
        hinterland_wert_euro:
          type: number
          description: 'Rear-plot share of the total value (bodenrichtwert_tatsaechlich × hinterland_faktor ×

            hinterland_flaeche_m2). Present only when the Vorderland/Hinterland split was used.

            '
        modell:
          type: string
          enum:
          - amtliche-standardformel
          description: The calculation model used.
        formel:
          type: string
          description: Human-readable description of the applied formula.
        hinweis:
          type: string
          description: 'Optional note. Can combine (space-joined) an extrapolation warning when a GFZ is outside the

            usual range with the mandatory Vorderland/Hinterland note (always present when that split is

            used — it is not an official model) and, depending on how far `hinterland_faktor` sits outside

            the documented 0.10–0.50 core range, one additional band-specific note.

            '
        disclaimer:
          type: string
          description: 'Mandatory note that this is an orienting conversion using the standard formula — not the

            zone-specific official conversion table, and not a market value.

            '
      required:
      - brw_input_euro_pro_m2
      - gfz_referenz
      - gfz_tatsaechlich
      - koeffizient_referenz
      - koeffizient_tatsaechlich
      - faktor
      - bodenrichtwert_tatsaechlich_euro_pro_m2
      - modell
      - formel
      - disclaimer
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
        status:
          type: integer
          description: HTTP status code
        reason:
          type: string
          enum:
          - trial_exhausted
          - no_active_plan
          description: Only on 402 limit_reached — why the quota is exhausted
        upgrade_url:
          type: string
          description: Only on 402 limit_reached — deep link to the billing page of the immokit.ai account (`produkt=bodenrichtwert`) to book a plan
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://bodenrichtwert.ai/oauth/authorize
          tokenUrl: https://bodenrichtwert.ai/oauth/token
          scopes: {}
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Static API key issued in the dashboard (Entwickler → API-Keys). Pass as

        `Authorization: Bearer <key>`. Alternative to the OAuth2 flow above —

        recommended for direct server-to-server integrations that skip the

        interactive OAuth consent screen.

        '
    QueryToken:
      type: apiKey
      in: query
      name: token
      description: 'The same API key as `BearerAuth`, passed as `?token=<key>` instead of in a header.


        Intended **only** for clients that cannot set request headers — Google Sheets

        `=IMPORTXML`/`=IMPORTDATA` and comparable spreadsheet importers. Every other client

        should use the `Authorization` header, which takes precedence when both are present.


        A credential in a URL is structurally weaker than one in a header: it is visible to

        anyone who can read the spreadsheet formula or the link. Responses authenticated this

        way are sent with `Cache-Control: no-store`, and our request logs and analytics record

        only the path, never the query string — but the key should still be a dedicated one

        with an expiry date, revocable in the dashboard.

        '