immokit-ai Bodenrichtwert API

openapi: 3.2.0
info:
  title: .ai Bodenrichtwert 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: Bodenrichtwert
paths:
  /api/bodenrichtwert:
    get:
      operationId: getBodenrichtwert
      summary: Get the official land value (Bodenrichtwert) for a German address
      description: 'Returns official land values (Bodenrichtwerte) in EUR per square meter for a given German address.


        Usage:

        - Pass a full German address as the "address" parameter (e.g. "Marienplatz 1, 80331 München" or "Unter den Linden 1, Berlin").

        - Without "nutzungsart", every land use type found at the address is returned (W residential, M mixed, G commercial, S special, L agricultural, F forestry, SO other).

        - Pass "nutzungsart" one or more times to filter to specific codes, e.g. "?nutzungsart=W&nutzungsart=G".

        - Breaking change (2026-04): the legacy code "LF" has been removed — clients must migrate to "L" and/or "F".


        Restrictions:

        - Schleswig-Holstein (SH), Sachsen (SN), and Bayern (BY) are legally excluded and return HTTP 451.

        - A valid Bearer token from OAuth authentication is required.'
      parameters:
      - name: address
        in: query
        required: true
        description: Full German address including street, house number, and city (e.g. "Friedrichstraße 43, 10117 Berlin")
        schema:
          type: string
        example: Unter den Linden 1, Berlin
      - name: nutzungsart
        in: query
        required: false
        description: 'Filter by land use type (official land-use category code). Repeat the parameter to filter

          by multiple codes at once, e.g. `?nutzungsart=W&nutzungsart=G` (not comma-separated):

          - W  = Wohnbaufläche (residential)

          - M  = Gemischte Baufläche (mixed residential/commercial)

          - G  = Gewerbliche Baufläche (commercial/industrial)

          - S  = Sonderbaufläche (special, e.g. hospitals, schools)

          - L  = Landwirtschaftliche Fläche (agricultural)

          - F  = Forstwirtschaftliche Fläche (forestry)

          - SO = Sonstige Fläche (other)


          Breaking change: the previous combined code `LF` has been removed — land and

          forestry are now separate codes (`L`, `F`), matching how the official source

          separates agricultural and forestry land. Clients that previously queried `LF` must migrate to `L` and/or `F`.


          If omitted, no filter is applied — every land use type found at the address is

          returned in `bodenrichtwerte`, sorted W, M, G, S, L, F, SO.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - W
            - M
            - G
            - S
            - L
            - F
            - SO
        style: form
        explode: true
      - name: format
        in: query
        required: false
        description: 'Response format. Defaults to `json`.


          `xml` returns the exact same payload as `application/xml` — every JSON key becomes an

          identically named element, with the same nesting, so the field documentation below

          applies to both formats. Entries of the `bodenrichtwerte` array are wrapped in

          `<bodenrichtwert>` elements; the document root is `<response>`.


          This exists for clients that cannot parse JSON, most notably Google Sheets

          `=IMPORTXML(url; xpath)`. Errors keep their HTTP status code in XML mode and use the

          same element names as the JSON error body (`error`, `message`, `status`).

          '
        schema:
          type: string
          enum:
          - json
          - xml
          default: json
        example: xml
      security:
      - OAuth2: []
      - BearerAuth: []
      - QueryToken: []
      responses:
        '200':
          description: Land value(s) found for the given address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BodenrichtwertResponse'
              example:
                address_input: Prenzlauer Allee 200, Berlin
                address_resolved: Prenzlauer Allee 200, 10405 Berlin - Prenzlauer Berg
                coordinates:
                  lat: 52.541454
                  lon: 13.412894
                bodenrichtwerte:
                - nutzungsart: Wohnbaufläche
                  code: W
                  brw_euro_pro_m2: 5000
                  stichtag: '2026-01-01'
                  gemeinde: Berlin
                  gutachterausschuss: Gutachterausschuss für Grundstückswerte Berlin
                  bodenrichtwertnummer: 0405W005
                  zonenbezeichnung: Prenzlauer Berg
                - nutzungsart: Gemischte Baufläche
                  code: M
                  brw_euro_pro_m2: 4200
                  stichtag: '2026-01-01'
                  gemeinde: Berlin
                  gutachterausschuss: Gutachterausschuss für Grundstückswerte Berlin
                  bodenrichtwertnummer: 0405M003
                  zonenbezeichnung: Prenzlauer Berg
                cache_hit: false
                attribution:
                  text: © Daten der Gutachterausschüsse für Grundstückswerte 2026, dl-de/by-2-0
                  license_url: https://www.govdata.de/dl-de/by-2-0
                  year: 2026
                disclaimer: Amtlicher Bodenrichtwert gemäß dl-de/by-2-0. Gutachterlicher Orientierungswert — kein Verkehrswert, kein Verkaufspreis, keine Rechtsberatung. Stichtag pro Eintrag beachten.
            application/xml:
              description: Returned when `format=xml`. Same payload, same field names — see the `format` parameter.
              schema:
                type: string
              example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n  <address_input>Prenzlauer Allee 200, Berlin</address_input>\n  <address_resolved>Prenzlauer Allee 200, 10405 Berlin - Prenzlauer Berg</address_resolved>\n  <coordinates>\n    <lat>52.541454</lat>\n    <lon>13.412894</lon>\n  </coordinates>\n  <bodenrichtwerte>\n    <bodenrichtwert>\n      <nutzungsart>Wohnbaufläche</nutzungsart>\n      <code>W</code>\n      <brw_euro_pro_m2>5000</brw_euro_pro_m2>\n      <stichtag>2026-01-01</stichtag>\n      <gemeinde>Berlin</gemeinde>\n      <gutachterausschuss>Gutachterausschuss für Grundstückswerte Berlin</gutachterausschuss>\n      <bodenrichtwertnummer>0405W005</bodenrichtwertnummer>\n      <zonenbezeichnung>Prenzlauer Berg</zonenbezeichnung>\n    </bodenrichtwert>\n  </bodenrichtwerte>\n  <cache_hit>false</cache_hit>\n  <attribution>\n    <text>© Daten der Gutachterausschüsse für Grundstückswerte 2026, dl-de/by-2-0</text>\n    <license_url>https://www.govdata.de/dl-de/by-2-0</license_url>\n    <year>2026</year>\n  </attribution>\n  <disclaimer>Amtlicher Bodenrichtwert gemäß dl-de/by-2-0. Gutachterlicher Orientierungswert — kein Verkehrswert, kein Verkaufspreis, keine Rechtsberatung. Stichtag pro Eintrag beachten.</disclaimer>\n</response>\n"
        '400':
          description: 'Missing or invalid parameters — `missing_address`, `invalid_nutzungsart`, or

            `invalid_format` (a `format` value other than `json` or `xml`).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Request blocked for billing reasons. Error code "limit_reached" = request

            quota exhausted — `reason` says why ("trial_exhausted" = 100-request trial

            cap used up, "no_active_plan" = trial over and no plan booked) and

            `upgrade_url` deep-links to the billing page of the immokit.ai account

            (`produkt=bodenrichtwert`). "payment_past_due" = the last

            payment failed and the grace period has elapsed (update payment details).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Address not found or no land value data available for this location
          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'
        '451':
          description: This state (Schleswig-Holstein, Sachsen, or Bayern) is legally excluded and provides no land-value data
          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'
        '503':
          description: Official land-value data source temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Bodenrichtwert
components:
  schemas:
    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.

            May be an empty string in some federal states where the official source does not

            publish the committee name in its feed (only the numeric committee ID).

            '
        bodenrichtwertnummer:
          type: string
          description: 'Unique identifier of the BRW zone within its Gutachterausschuss. Use this

            when referencing a specific zone in a formal appraisal — the value is

            stable across requests for the same coordinate.

            '
        zonenbezeichnung:
          type: string
          description: 'Human-readable name of the BRW zone — often a district or quarter

            name (e.g. "Regierungsviertel" for the government quarter in Hannover),

            optionally combined with the land use code (e.g. "Stederdorf W" for the

            Wohnbau zone in the Stederdorf district).

            '
        bauweise:
          type: string
          description: 'Permitted building configuration as published in the land development plan

            (e.g. "offen" = detached, "geschlossen" = attached). Often unset.

            '
        geschossflaechenzahl:
          type: number
          description: 'Floor Area Ratio (GFZ) permitted in the zone — the ratio of total gross

            floor area to plot area. Input for the price conversion if the subject

            plot has a different FAR than the one the BRW was calibrated for.

            '
        grundflaechenzahl:
          type: number
          description: 'Site Coverage Ratio (GRZ) — the ratio of built-over area to plot area.

            '
        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

            primarily in dense commercial / high-rise zones instead of GFZ.

            '
        wertrel_geschossflaechenzahl:
          type: number
          description: 'Reference Floor Area Ratio ("wertrelevante GFZ", WGF) — the GFZ the

            expert committee used as the basis for this Bodenrichtwert. If the

            subject plot has a different GFZ, the BRW must be re-indexed against

            the committee''s published conversion table. Without this field a

            professional appraisal cannot adjust the value accurately.

            '
    Quelle:
      type: object
      description: 'One source with its licence. The wording in `provider` is prescribed — do not

        paraphrase it when displaying or forwarding the data.

        '
      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
    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
    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: '#/components/schemas/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

            emergency window: it could not be re-checked against the official source just

            now, so the last known value was returned instead of an error. A background

            refresh is triggered, so a later request for the same coordinate normally

            answers fresh again. The field is omitted entirely when the value was fresh.


            This is not a correctness warning. Bodenrichtwerte are published for an annual

            Stichtag, and the `stichtag` on every entry remains the authoritative reference

            for what point in time the value applies to.

            '
        attribution:
          $ref: '#/components/schemas/Attribution'
        quelle:
          type: array
          description: 'Every source whose data is in this response, each with its licence. Two entries:

            the Gutachterausschuss data for the land value, and the BKG address service that

            resolved the address into the coordinate the value was looked up at. Both are

            licensed dl-de/by-2-0 and both must stay visible when you pass the data on —

            `attribution` names only the first of them.

            '
          items:
            $ref: '#/components/schemas/Quelle'
        disclaimer:
          type: string
          description: 'Pflicht-Hinweis, dass der Bodenrichtwert ein gutachterlicher Orientierungswert ist —

            kein Verkehrswert, kein Verkaufspreis, keine Rechtsberatung. Muss bei Weitergabe sichtbar bleiben.

            '
  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.

        '