Standortanalysen direkt in Ihrer Software

Gekürzt: jede Liste zeigt nur ihren ersten Eintrag. Vollständig enthält die Antwort sechs Einträge in tiles, bis zu drei in info_tiles, drei in eignungsprofile und bis zu sechs datenblaetter. Das GeoJSON-Polygon der Zelle ist hier weggelassen. Die Werte stammen aus unserem Testdatensatz, die Struktur ist die der echten Antwort.

{
  "address": "Musterstraße 1, 66111 Musterstadt",
  "address_note": null,
  "baustruktur": {
    "ampel": "info",
    "available": true,
    "detail": {
      "dominant_class": "3bis6_wohnungen",
      "shares": {
        "13undmehr_wohnungen": 0.16,
        "1_wohnung": 0.08,
        "2_wohnungen": 0.06,
        "3bis6_wohnungen": 0.4,
        "7bis12_wohnungen": 0.3
      },
      "tier_shares": {
        "gross": 0.16,
        "klein": 0.14,
        "mittel": 0.7
      }
    },
    "key": "baustruktur",
    "kind": "label",
    "label": "Baustruktur",
    "value": "Mehrfamilienhaus-geprägt"
  },
  "comparison": {
    "gemeinde_available": true,
    "gemeinde_name": "Musterstadt",
    "metrics": [
      {
        "key": "durchschnittsalter",
        "label": "Durchschnittsalter",
        "note": null,
        "raw": 42.5,
        "scopes": {
          "deutschland": {
            "band_key": "durchschnittlich",
            "band_label": "Durchschnittlich",
            "percentile": 66
          },
          "gemeinde": {
            "band_key": "durchschnittlich",
            "band_label": "Durchschnittlich",
            "percentile": 66
          },
          "stadtteil": {
            "band_key": "durchschnittlich",
            "band_label": "Durchschnittlich",
            "percentile": 66
          }
        },
        "unit": "years",
        "value": "42,5 Jahre"
      }
    ],
    "stadtteil_available": true,
    "stadtteil_name": "Musterviertel"
  },
  "data_version": "golden000000",
  "datenblaetter": [
    {
      "rows": [
        {
          "denominator": "Personen",
          "label": "Bevölkerungsdichte",
          "observed": "Stichtag 15. Mai 2022",
          "raw": 240,
          "sub": "Median der Wohnlagen in Deutschland: 30 Personen je Hektar",
          "unit": "persons_per_ha",
          "value": "240 Personen je Hektar",
          "vintage": "zensus2022"
        }
      ],
      "title": "Soziodemografie",
      "vintages": [
        {
          "end": "2022-05-15",
          "id": "zensus2022",
          "period_de": "Stichtag 15. Mai 2022",
          "source": "Zensus 2022",
          "start": "2022-05-15"
        }
      ]
    }
  ],
  "details": {
    "laerm": {
      "any_exposure": true,
      "entries": [
        {
          "hits": 5,
          "period": "lden",
          "source": "road",
          "value": "66 dB Lden"
        }
      ],
      "overall": "66 dB Lden (Straße)",
      "observed": "Kartierung 2022",
      "vintage": "uba_laerm"
    },
    "wasser": {
      "entries": [
        {
          "area_type": "1",
          "coverage_pct": 8.0,
          "depth": "0,8 m",
          "family": "river",
          "scenario": "hq100"
        }
      ],
      "observed": "Zusammenstellung 2025, Stand der Länderkarten unterschiedlich",
      "starkregen": {
        "deep_pct": 3.0,
        "flooded_pct": 12.0,
        "observed": "Ausgabe 2025",
        "vintage": "bkg_starkregen"
      },
      "vintage": "bfg_hochwasser",
      "zuers_class": 3
    }
  },
  "eignungsprofile": [
    {
      "ampel": "green",
      "available": true,
      "detail": {
        "band": "Gut geeignet",
        "components_total": 6,
        "components_used": 6,
        "gruen": 0.52,
        "hitze": 0.25,
        "kita": 1.0,
        "ruhe": 0.6,
        "schule": 1.0,
        "spielplatz": 0.85
      },
      "key": "profil_familie",
      "kind": "score",
      "label": "Familien-Eignung",
      "value": 72
    }
  ],
  "fallback_direction": null,
  "fallback_distance_m": null,
  "fallback_ring": 0,
  "from_cache": false,
  "gemeinde": {
    "land": "SL",
    "name": "Musterstadt",
    "published": true,
    "slug": "musterstadt"
  },
  "generated_at": "2026-07-16T12:00:00+00:00",
  "gitter_id": "crs3035res100mn2691750e4341150",
  "headline": {
    "ampel": "red",
    "category_key": "water_risk_level",
    "category_label": "Überflutungsgefahr",
    "has_unknown_risk": false,
    "level": "Hoch",
    "note": "Höchste Gefahr oder Belastung der Rasterzelle. Kein Mittelwert über alle Kategorien."
  },
  "info_tiles": [
    {
      "ampel": "green",
      "available": true,
      "detail": null,
      "key": "miete_level",
      "kind": "level",
      "label": "Mietniveau",
      "value": "Gering"
    }
  ],
  "lat": 49.234,
  "lon": 6.994,
  "match": "house",
  "near_border": true,
  "neighbour_fallback": false,
  "report_type": "voll",
  "resolved_at": "2026-07-16T12:00:00+00:00",
  "stadtteil": {
    "city_slug": "musterstadt",
    "name": "Musterviertel",
    "published": true,
    "slug": "musterviertel"
  },
  "starkregen_coverage": "verfuegbar",
  "tiles": [
    {
      "ampel": "red",
      "available": true,
      "detail": {
        "flood_layer_assessed": true,
        "flood_risk_label": "HQ100",
        "flood_zuers_class": 3,
        "hochwasser_present": true,
        "hochwasser_severity": 3,
        "starkregen_assessed": true,
        "starkregen_deep_pct": 3.0,
        "starkregen_flooded_pct": 12.0,
        "starkregen_max_class": 3,
        "starkregen_severity": 2
      },
      "key": "water_risk_level",
      "kind": "level",
      "label": "Überflutungsgefahr",
      "value": "Hoch"
    }
  ],
  "verdict": "Diese Lage bringt eine erhöhte Hochwasser- und Starkregengefahr sowie eine hohe sommerliche Hitzebelastung mit sich.",
  "meta": {
    "api_version": "v1",
    "request_id": "b3f1c8e2-4a17-4d90-9f21-7c0a5e6d1234",
    "ags": "10041000",
    "gitter_id": "crs3035res100mn2691750e4341150",
    "resolved_address": "Musterstraße 1, 66111 Musterstadt",
    "match": "house",
    "address_note": null,
    "fallback_ring": 0,
    "data_version": "golden000000",
    "composites_version": "3.2",
    "generated_at": "2026-07-16T12:00:00+00:00",
    "from_cache": false,
    "idempotent_replay": false,
    "sandbox": false,
    "credits_charged": 1,
    "narration_status": "not_requested",
    "credits_remaining": 499
  }
}

Denselben Aufbau liefert der kostenlose Testschlüssel, bevor Sie ein Paket buchen. Sie sehen also vor dem Kauf genau das, was Sie später bekommen.

Jede Anfrage trägt einen API-Schlüssel. Schlüssel legen Sie in Ihrem Konto unter „API-Zugang“ an. Der Schlüssel wird genau einmal angezeigt, danach liegt bei uns nur noch ein Hash. Verlieren Sie ihn, legen Sie einen neuen an.

Ein Schlüssel ist ein Passwort. Legen Sie ihn nicht in ein öffentliches Repository und geben Sie ihn nicht im Browser preis, denn er wirkt ohne weitere Anmeldung.

Authorization: Bearer wd_IHR_SCHLUESSEL
# alternativ
X-API-Key: wd_IHR_SCHLUESSEL

GET /api/v1/account

Prüft den Schlüssel und nennt den Verbrauch des laufenden Tages. Der Aufruf verbraucht selbst kein Kontingent.

curl -H "Authorization: Bearer wd_..." \
  https://api.wohn-data.de/api/v1/account

POST /api/v1/report

Eine Adresse hinein, ein vollständiger Report heraus. Geliefert wird immer die vollständige Auswertung, nicht die kostenlose Kurzfassung. Felder im Anfragekörper:

• address (Pflicht): die zu prüfende Adresse in Deutschland.
• include_narration (optional, Standard false): liefert zusätzlich den KI-Text als report_text. Kostet zwei Credits statt einem und dauert deutlich länger. Berechnet werden die zwei Credits nur, wenn der Text auch geliefert wird. Ob das der Fall ist, steht in meta.narration_status.
• wide_fallback (optional, Standard false): liegt die Adresse in einer Rasterzelle ohne Zensus-Daten, suchen wir ohne diesen Schalter in den acht angrenzenden Zellen. Mit ihm suchen wir auch in den 16 Zellen dahinter und nehmen die bewohnte Zelle, deren Mittelpunkt der Adresse am nächsten liegt. Das ist eine geänderte Anfrage und keine Wiederholung. Senden Sie sie deshalb mit einem neuen Idempotency-Key.

Jede erfolgreiche Antwort enthält einen Block meta mit den Feldern, die Sie zum Zusammenführen mit eigenen Daten brauchen:

• ags: der achtstellige Amtliche Gemeindeschlüssel. Der Schlüssel, über den Sie unsere Ergebnisse mit eigenen Beständen oder amtlichen Statistiken verbinden.
• gitter_id: die 100-Meter-Rasterzelle, auf die sich alle Werte beziehen. Zwei Adressen mit derselben Zelle haben identische Werte.
• resolved_address: die Adresse, die das Geocoding tatsächlich getroffen hat. Mit Ihrer Eingabe vergleichen, um stille Fehltreffer bei Tippfehlern zu erkennen.
• fallback_ring: 0 heißt, die Adresse liegt in einer bewohnten Zelle. 1 heißt, dass die nächstgelegene bewohnte angrenzende Zelle verwendet wurde, 2 eine Zelle aus der erweiterten Suche (nur mit wide_fallback). Wie weit ihr Mittelpunkt von der Adresse entfernt ist und in welcher Richtung er liegt, steht in fallback_distance_m und fallback_direction. Für Auswertungen sollten Sie diese Fälle kennzeichnen.
• data_version und composites_version: Stand der Daten und Version der Berechnungsvorschrift. Beide mitspeichern, sonst lässt sich ein Ergebnis später nicht mehr nachvollziehen.
• credits_charged: was der Aufruf gekostet hat.
• credits_remaining: das Guthaben nach dem Aufruf. Bei Enterprise und im Testzugang ist es null, was nicht null Credits bedeutet.
• narration_status: was aus dem KI-Text geworden ist. not_requested heißt, er war nicht angefragt. delivered heißt, er steht in report_text. blocked heißt, das Modell hat keinen Text geliefert. busy heißt, die Kapazität war erschöpft und ein späterer Versuch kann gelingen. failed heißt, der Aufruf des Modells ist fehlgeschlagen. Nur bei delivered kostet der Aufruf zwei Credits, sonst einen.
• request_id: identisch mit dem Antwort-Header X-Request-ID.

Alle Werte gelten für eine 100-Meter-Rasterzelle, aber nicht jeder ist dort gemessen. Manche sind Mittel über ein Quadrat um die Zelle, manche zählen in einem Kreis, manche stammen aus einem 1-km-Rasterfeld, und manche sind Meldungen der Anbieter. Für Auswertungen gilt die Bezugsfläche in der letzten Spalte.

Fehler tragen den passenden HTTP-Status und in error ein Objekt mit code, message, request_id und retry. Werten Sie immer den code aus, nicht den Text. Der Text kann sich ändern, der Code nicht.

{
  "error": {
    "code": "ADDRESS_NOT_FOUND",
    "message": "The address could not be geocoded. ...",
    "request_id": "9f2c1ab73d4e5f60",
    "retry": "fix_request"
  }
}

Das gilt für alle Fehler, auch für ungültige Eingaben. Bei einer fehlerhaften Anfrage kommt INVALID_REQUEST zurück, zusätzlich mit details und der Angabe, welches Feld beanstandet wurde.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is not valid. Check: address.",
    "request_id": "9f2c1ab73d4e5f60",
    "retry": "fix_request",
    "details": [
      { "field": "address", "reason": "String should have at least 3 characters",
        "type": "string_too_short" }
    ]
  }
}

Ein 404 ist ein endgültiges Ergebnis für diese Adresse und sollte nicht wiederholt werden. Was nach einem Fehler zu tun ist, steht in retry. fix_request heißt, dieselbe Anfrage bekommt dieselbe Antwort, sie muss geändert werden. fix_account heißt, erst Schlüssel oder Guthaben in Ordnung bringen. Danach darf derselbe Idempotency-Key wiederholt werden. retry_later heißt, dieselbe Anfrage später erneut senden und dabei Retry-After beachten.

Bricht eine Verbindung ab, wissen Sie nicht, ob der Aufruf angekommen ist. Schicken Sie deshalb bei Massenläufen einen Idempotency-Key mit, zum Beispiel Ihre Datensatznummer. Ein Aufruf mit demselben Schlüssel wird dann höchstens einmal berechnet, auch wenn die Verbindung abbricht oder unser Server währenddessen neu startet. Bei einer Wiederholung steht in der Antwort meta.idempotent_replay: true und meta.credits_charged: 0.

curl -X POST https://api.wohn-data.de/api/v1/report \
  -H "Authorization: Bearer wd_..." \
  -H "Idempotency-Key: batch-2026-08-04-row-00042" \
  -H "Content-Type: application/json" \
  -d '{"address": "Musterstraße 1, 66111 Saarbrücken"}'

• Derselbe Schlüssel mit einem anderen Anfragekörper ergibt 422 IDEMPOTENCY_KEY_REUSED. Das ist Absicht, denn es ist fast immer ein Fehler im aufrufenden Programm.
• War der erste Versuch erfolglos, liefert die Wiederholung denselben Fehler zurück, ohne erneut zu rechnen.
• Vorübergehende Fehler wie 429 oder 503 geben den Schlüssel wieder frei, ebenso 402, damit derselbe Aufruf nach dem Kauf eines Pakets durchgeht.
• Bricht ein Aufruf auf unserer Seite ab, ist der Schlüssel nach spätestens zehn Minuten wieder frei. War der abgebrochene Aufruf schon berechnet, liefert die Wiederholung den Report ohne erneute Berechnung.
• Schlüssel gelten mindestens 24 Stunden. Ein Aufruf mit einem abgelaufenen Schlüssel ist ein neuer Aufruf und wird berechnet.

Wir speichern dabei nicht die Antwort, sondern nur, wie der Aufruf ausgegangen ist. So bleibt es dabei, dass wir Ihre Adressen nicht vorhalten. Die Antwort wird bei einer Wiederholung deshalb neu erzeugt. Die Werte sind dieselben, solange sich Datenstand und Berechnungsvorschrift nicht geändert haben, was meta.data_version und meta.composites_version zeigen. request_id und generated_at sind bei jeder Antwort neu.

Für die Entwicklung legen Sie im Konto einen Testschlüssel an. Er beginnt mit wd_test_ und liefert für jede Anfrage einen festen Beispielreport in genau der Struktur, die auch die echten Antworten haben.

• verbraucht kein Kontingent,
• unterliegt keiner Gleichzeitigkeitsgrenze,
• antwortet immer mit meta.sandbox: true. Prüfen Sie dieses Feld, damit Testdaten nie in Ihre Auswertung geraten.

Die Werte beziehen sich immer auf dieselbe Adresse und ändern sich nicht, egal was Sie anfragen. Der Testzugang dient dazu, Ihre Anbindung zu schreiben, nicht dazu, Ergebnisse zu prüfen.

Damit Sie auch die Fehlerfälle Ihrer Anbindung schreiben können, antwortet der Testzugang auf die folgenden Adressen mit dem jeweiligen Fehler oder Teilergebnis statt mit dem Beispielreport, in genau der Form einer echten Antwort. Die Adresse wird genau so als address gesendet.

Das Kontingent gilt je Konto, nicht je Schlüssel. Zusätzliche Schlüssel erhöhen es also nicht, sie dienen der Trennung Ihrer Systeme. Die genaue Zahl steht in Ihrem Konto unter „API-Zugang“.

Pro Konto dürfen höchstens drei Anfragen gleichzeitig laufen. Darüber antworten wir sofort mit 429 TOO_MANY_CONCURRENT_REQUESTS, damit Ihr Programm reagieren kann, statt in einen Timeout zu laufen. Ist der Dienst insgesamt ausgelastet, kommt stattdessen 503.

Für größere Bestände empfehlen wir wenige parallele Verbindungen statt vieler, und include_narration im Massenbetrieb ausgeschaltet zu lassen: der KI-Text ist der langsamste und teuerste Teil, und ohne ihn verlassen Ihre Daten unseren Verarbeitungskreis nicht in Richtung eines KI-Anbieters.

Jede Antwort trägt den Header X-Request-ID. Wenn Sie eine Anfrage reklamieren, nennen Sie diesen Wert, dann finden wir den Vorgang. Sie können auch selbst einen Wert mitschicken, dann verwenden wir Ihren. Er muss zwischen 8 und 64 Zeichen lang sein und darf nur Buchstaben, Ziffern, Punkt, Bindestrich und Unterstrich enthalten. Andernfalls vergeben wir einen eigenen Wert, statt Ihren stillschweigend zu verändern.

In Ihrem Konto finden Sie unter „API-Verlauf“ die Aufrufe der letzten 30 Tage mit Zeitpunkt, Status, Fehlercode, Dauer und verwendetem Schlüssel. Die abgefragte Adresse steht dort nicht, weil wir sie nicht speichern. Genau dafür ist die selbst gesetzte Kennung gedacht: Schicken Sie Ihre Datensatznummer als X-Request-ID mit, dann verbinden Sie den Verlauf mit Ihren eigenen Daten, ohne dass uns die Adresse bekannt wird.

Bitte übermitteln Sie in diesem Feld keine personenbezogenen Daten, also keine Namen und keine Kundendaten. Eine interne Nummer erfüllt denselben Zweck.

Der Pfad enthält die Version. Innerhalb von v1 nehmen wir nur ergänzende Änderungen vor, etwa zusätzliche Felder. Ihre Auswertung sollte unbekannte Felder daher ignorieren statt an ihnen zu scheitern. Eine Änderung, die bestehende Felder entfernt oder umdeutet, erscheint als v2.

Der Schlüssel erlaubt genau das, was die AGB sonst untersagen, nämlich die systematische Abfrage. Erlaubt ist die Nutzung der Ergebnisse in Ihren eigenen Prozessen und gegenüber Ihrer eigenen Kundschaft. Untersagt bleiben der Aufbau eines eigenen oder konkurrierenden Datenbestands aus den Antworten, die Weitergabe als eigenes Produkt und der Weiterverkauf einzelner Auskünfte an Verbraucher. Die Quellenangaben der Datenlieferanten sind mitzuführen, siehe Datenquellen.

Wenn Sie Adressen Ihrer eigenen Kundschaft an die Schnittstelle senden, verarbeiten wir diese in Ihrem Auftrag. Dafür schließen wir vor der Freischaltung einen Vertrag zur Auftragsverarbeitung nach Art. 28 DSGVO. Sprechen Sie uns darauf an, wir halten ihn bereit.

Die Ergebnisse sind eine Information und kein Gutachten. Das gilt über die Schnittstelle genauso wie auf der Website, siehe Methodik & Grenzen der Daten.