Somantic API-Dokumentation

Alle Endpunkte teilen sich die Basis-URL https://www.somantic.net/api. Anfragen und Antworten erfolgen im JSON-Format. Erstelle zunächst einen kostenlosen API-Schlüssel im Entwickler-Dashboard – auf der BASIC-Stufe ohne Kreditkarte.

Übergib deinen geheimen Schlüssel bei jeder Anfrage im X-API-Key-Header. Alternativ wird auch ein Bearer-Token im Authorization-Header akzeptiert. Schlüssel haben die Form som_live_… und werden nur einmal bei der Erstellung angezeigt – bewahre sie sicher auf und gib sie niemals im Client-Code preis.

X-API-Key: som_live_DEIN_SCHLUESSEL
# oder
Authorization: Bearer som_live_DEIN_SCHLUESSEL

Jede API wird separat auf Monatsbasis abgerechnet. Die Nutzung wird zu Beginn jedes Kalendermonats zurückgesetzt und ist in deinem Dashboard sichtbar. Auf der kostenlosen FREE-Stufe gibt die API nach Erreichen des inkludierten Kontingents 429 Too Many Requests zurück, bis du upgradest. Bezahlte Stufen liefern weiterhin Anfragen aus und rechnen Mehrverbrauch pro Anfrage ab. Alle Preise inkl. 19 % MwSt.

Eine Meta-Suchmaschine als flexibler GraphQL-Endpunkt: Sie durchsucht die aktiven Inserate für Häuser und Wohnungen aus zahlreichen deutschen Portalen, damit Entwickler und Nutzer gezielt die passenden Objekte finden und zum Original-Inserat beim Anbieter gelangen. Jedes Inserat wird mit dem fairen Schätzwert unseres Bewertungsmodells (som_model_price), der Abweichung vom Markt (som_model_percentage) sowie Cashflow- und ROI-Kennzahlen angereichert. Frage all_appartments oder all_houses mit dem filters-Argument ab und wähle genau die Felder, die du brauchst. Praxisnahe Vorlagen findest du unter Beispielabfragen.

Dasselbe Objekt wird häufig auf mehreren Portalen gleichzeitig inseriert. Die Suche zeigt jedes dieser Inserate als eigenen Treffer – mit eigener immo_id und dem Quellportal im Feld source –, damit du siehst, wo ein Objekt überall angeboten wird und zu welchem Preis. Willst du je Objekt nur einen Treffer, gruppiere nach dem Titel (kleingeschrieben, Leerzeichen zusammengefasst), square_meter, rooms und action und behalte das jüngste Inserat: Nach dieser Signatur fasst auch unsere Bewertung Mehrfach-Inserate zusammen. Der Preis gehört bewusst nicht dazu, weil Portale nach einer Preissenkung oft noch den alten zeigen.

Verfügbare Abfragen

Alle Abfragen akzeptieren die Argumente filters, page, per_page (max. 100), order_by (derzeit nur "-uptime_date", der Standard: zuletzt erfasste Inserate zuerst) sowie equity_percentage, interest und repayment zur Anpassung der Cashflow- und ROI-Berechnung. Die API liefert immer nur aktive Inserate: is_active ist stets true, auch wenn du etwas anderes angibst.

Aktualität. date (im MCP-Server last_seen) nennt, wann Somantic das Inserat zuletzt als online bestätigt hat. Nicht mehr bestätigte Inserate werden in der Regel nach 3 Tagen aus den Ergebnissen entfernt.

Keine Straße, keine Koordinaten. Die genaue Adresse eines angebotenen Objekts ist ein personenbezogenes Datum: Über sie lassen sich Eigentümer, Verkäufer oder Mieter identifizieren, und viele Inserenten veröffentlichen sie deshalb bewusst nicht. Die Lage eines Inserats geben Immobilien-API und MCP-Server daher nur über Postleitzahl und Ort an. Geografisch eingrenzen lässt sich die Suche trotzdem, mit zipcode_in, city oder lat_gt/lat_lt. Die genaue Lage steht, soweit der Inserent sie freigibt, im Original-Inserat.

Inserate sind Angebote Dritter. Jede Antwort trägt deshalb unter extensions.attribution die Nutzungsregel: Wer ein Inserat anzeigt, nennt das Quellportal (source) und verlinkt das Original (url).

Beispielabfrage

{
  all_appartments(
    filters: { city: "München", price_lt: 600000, square_meter_gt: 50 }
    per_page: 5
    order_by: "-uptime_date"
  ) {
    edges {
      node {
        immo_id
        title
        city
        price
        square_meter
        rooms
        price_per_square_meter
        som_model_price        # fairer Schätzwert unseres Modells
        som_model_percentage   # % über/unter Markt
        roi
      }
    }
  }
}

Abfrage senden

curl https://www.somantic.net/api/graphql \
  -H "X-API-Key: som_live_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ all_appartments(filters:{city:\"München\"}, per_page:5){ edges{ node{ immo_id title price som_model_price roi } } } }"}'

Jedes Ergebnis wird als Relay-Verbindung zurückgegeben – die Objekte stehen unter edges → node. Wähle in der node-Auswahl beliebige der folgenden Felder; du erhältst ausschließlich die angefragten Felder zurück. avg_appartments und avg_houses liefern zusätzlich die aggregierten Felder avg_price_per_square_meter und avg_rent_per_square_meter.

Abfragbare Felder

Filter

Übergib Filter als filters-Objekt. Numerische und Datumsfelder unterstützen die Suffixe _lt, _gt, _lte und _gte (kombiniere _gt und _lt für Bereiche). _in erwartet eine Liste, _exists einen Boolean und _contains eine case-insensitive Teilstring-Suche.

Sende jede dieser Abfragen per POST an https://www.somantic.net/api/graphql – im JSON-Body unter dem Schlüssel query und mit deinem X-API-Key-Header (siehe Abfrage senden).

{
  all_appartments(
    order_by: "-uptime_date"
    per_page: 10
    page: 1
    filters: { is_active: true, action: "kaufen", location: "bl-bayern" }
  ) {
    edges {
      node {
        uptime_date
        url
        square_meter
        price
      }
    }
  }
}

{
  all_appartments(
    order_by: "-uptime_date"
    per_page: 10
    page: 2
    filters: { is_active: true, action: "kaufen", location: "bl-bayern" }
  ) {
    edges { node { uptime_date url square_meter price } }
  }
}

{
  all_houses(
    order_by: "-uptime_date"
    per_page: 20
    page: 1
    filters: { is_active: true, action: "kaufen", location: "bl-baden-wuerttemberg" }
  ) {
    edges {
      node {
        uptime_date
        url
        square_meter
        property_square_meter
        price
      }
    }
  }
}

{
  avg_appartments(filters: { is_active: true, action: "kaufen", location: "bl-baden-wuerttemberg" }) {
    edges { node { avg_price_per_square_meter } }
  }
}

{
  avg_appartments(filters: { is_active: true, action: "mieten", location: "hamburg" }) {
    edges { node { avg_rent_per_square_meter } }
  }
}

{
  total_appartments_count(filters: { is_active: true, action: "mieten", location: "hamburg" })
}

{
  all_appartments(
    order_by: "-uptime_date"
    per_page: 100
    page: 1
    filters: { is_active: true, city: "Hagen", action: "mieten" }
  ) {
    edges {
      node {
        immo_id
        url
        source
        title
        location
        city
        zipcode
        rent_price
        warm_rent_price
        extra_charges_price
        rent_per_square_meter
        square_meter
        year_of_construction
        uptime_date
      }
    }
  }
}

{
  all_appartments(
    order_by: "-uptime_date"
    per_page: 100
    page: 1
    filters: { is_active: true, zipcode_in: [23552], action: "kaufen" }
  ) {
    edges {
      node {
        immo_id
        url
        source
        title
        location
        city
        state
        zipcode
        price
        price_per_square_meter
        square_meter
        year_of_construction
        uptime_date
      }
    }
  }
}

{
  all_appartments(
    order_by: "-uptime_date"
    per_page: 25
    filters: { is_active: true, action: "kaufen", city: "Leipzig", som_model_percentage_lt: -10 }
  ) {
    edges {
      node {
        immo_id
        url
        title
        price
        som_model_price
        som_model_percentage
        price_per_square_meter
      }
    }
  }
}

{
  all_appartments(
    order_by: "-uptime_date"
    per_page: 25
    equity_percentage: 0.2
    interest: 0.042
    repayment: 0.02
    filters: { is_active: true, action: "kaufen", cashflow_gt: 0 }
  ) {
    edges {
      node {
        immo_id
        url
        title
        price
        rooms
        square_meter
        cashflow
        roi
        som_model_rent
      }
    }
  }
}

Über das Model Context Protocol (MCP) sucht ein KI-Agent – etwa in Claude, ChatGPT, Codex oder einer eigenen Anwendung – direkt über die Somantic-Suche, ohne dass du Abfragen selbst baust. Der Endpunkt ist https://www.somantic.net/api/mcp/ (Streamable HTTP, zustandslos; mit Schrägstrich am Ende). Die Liste der Tools ist ohne Anmeldung abrufbar. Jeder Tool-Aufruf braucht entweder die Anmeldung mit deinem Somantic-Konto (OAuth) oder einen API-Schlüssel und zählt als eine Anfrage in deinem API-Kontingent – die kostenlose Stufe reicht zum Ausprobieren (Preise).

Die Tools liefern Fakten, die Bewertung von Somantic (somantic_valuation_eur, price_vs_valuation_pct) und den Weg zum Angebot (source_portal, source_url) sowie mit last_seen, wann Somantic das Inserat zuletzt als online bestätigt hat. Keine Straße und keine Koordinaten (zum Schutz der Eigentümer und Bewohner, siehe Immobilien-API), keinen Text des Inserenten und keine Bilder. Zeigt dein Agent ein Inserat an, nennt er das Quellportal und verlinkt source_url; es gelten die API-Bedingungen in Ziffer 15 der AGB, für KI-Assistenten insbesondere Ziffer 15.5a.

Einrichtung

Mit der Anmeldung legt Somantic in deinem Entwickler-Dashboard den Schlüssel „KI-Assistent: …“ an, über den die Aufrufe laufen. Widerrufst du ihn dort, ist die Verbindung getrennt.

• claude.ai (gilt auch für Claude Desktop und die Claude-App): am einfachsten über den Eintrag im Claude-Verzeichnis („Connect“), sonst Settings → Connectors → „Add custom connector“ mit der URL. Beim ersten Aufruf meldest du dich mit deinem Somantic-Konto an. Alternativ mit API-Schlüssel: „No sign-in“ wählen und unter „Request headers“ X-API-Key mit deinem Schlüssel eintragen – sofern dein Konto diesen Abschnitt anzeigt.
• ChatGPT: am einfachsten über den Eintrag im ChatGPT-Verzeichnis („Install plugin“), sonst unter chatgpt.com/plugins über „+“ → „Add custom MCP server“ die URL eintragen, als Authentifizierung OAuth wählen und als Plugin anlegen. Im Chat dann mit „@“ auswählen; beim ersten Aufruf meldest du dich mit deinem Somantic-Konto an.

Claude Code

# Mit Anmeldung: danach in Claude Code /mcp → somantic → Authenticate
claude mcp add --transport http somantic https://www.somantic.net/api/mcp/

# Oder mit API-Schlüssel
claude mcp add --transport http somantic https://www.somantic.net/api/mcp/ \
  --header "X-API-Key: som_live_DEIN_SCHLUESSEL"

Claude Code (.mcp.json)

{
  "mcpServers": {
    "somantic": {
      "type": "http",
      "url": "https://www.somantic.net/api/mcp/",
      "headers": { "X-API-Key": "som_live_DEIN_SCHLUESSEL" }
    }
  }
}

Claude Desktop mit API-Schlüssel (claude_desktop_config.json, braucht Node.js)

{
  "mcpServers": {
    "somantic": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.somantic.net/api/mcp/",
               "--header", "X-API-Key:${SOMANTIC_API_KEY}"],
      "env": { "SOMANTIC_API_KEY": "som_live_DEIN_SCHLUESSEL" }
    }
  }
}

Codex CLI

# ~/.codex/config.toml
[mcp_servers.somantic]
url = "https://www.somantic.net/api/mcp/"
# Schlüssel aus der Umgebungsvariable SOMANTIC_API_KEY. Ohne diese Zeile
# meldest du dich mit `codex mcp login somantic` an.
bearer_token_env_var = "SOMANTIC_API_KEY"

Cursor und VS Code

// Cursor: ~/.cursor/mcp.json
{
  "mcpServers": {
    "somantic": {
      "url": "https://www.somantic.net/api/mcp/",
      "headers": { "X-API-Key": "som_live_DEIN_SCHLUESSEL" }
    }
  }
}

// VS Code: .vscode/mcp.json
{
  "servers": {
    "somantic": {
      "type": "http",
      "url": "https://www.somantic.net/api/mcp/",
      "headers": { "X-API-Key": "som_live_DEIN_SCHLUESSEL" }
    }
  }
}
// Ohne "headers" melden sich beide mit dem Somantic-Konto an.

Direkter Aufruf

curl https://www.somantic.net/api/mcp/ \
  -H "X-API-Key: som_live_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "search_listings",
                  "arguments": {"q": "Leipzig", "transaction": "kaufen",
                                "price_max": 300000, "price_below_market": true}}}'

Liefert eine sofortige Miet- und Kaufpreisschätzung für jede deutsche Adresse – auf Basis echter Vergleichsangebote aus derselben Lage. Sende ein POST an /estimate mit den Objektdaten.

Mehrfach-Inserate zählen nur einmal. Dieselbe Wohnung steht oft gleichzeitig auf mehreren Portalen. Vor der Berechnung werden Vergleichsobjekte portalübergreifend zusammengefasst, sodass ein dreifach inseriertes Objekt den Schätzwert nicht dreifach beeinflusst. sample_size nennt die Zahl der tatsächlich verwendeten – also bereits bereinigten – Vergleichsobjekte.

Anfrage-Body

Anfrage senden

curl https://www.somantic.net/api/estimate \
  -H "X-API-Key: som_live_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "typ": "wohnung",
    "street": "Marienplatz 1",
    "postcode": "80331",
    "city": "München",
    "square_meters": 75,
    "rooms": 3,
    "year_of_construction": 1990
  }'

Beispielantwort

{
  "estimates": {
    "rent": 1650,             // geschätzte monatliche Kaltmiete (€)
    "price": 712500,          // geschätzter Kaufpreis (€)
    "price_range": {          // Quartilsband über die Vergleichsobjekte
      "low": 664000,
      "high": 758000
    },
    "rent_range": { "low": 1540, "high": 1760 },
    "price_per_square_meter": {
      "count": 46, "mean": 9500.0, "median": 9420.0,
      "p25": 8850.0, "p75": 10110.0, "min": 7200.0, "max": 12400.0
    },
    "rent_per_square_meter": { "count": 31, "mean": 22.0, "median": 21.8, ... },
    "similar_properties": [ ... ]   // Vergleichsobjekte; lat/lon auf ca. 1 km gerundet
  },
  "confidence": {
    "price": "high",          // high | medium | low | none
    "rent": "medium",
    "sample_size": 46,        // Vergleichsobjekte nach Filterung
    "cluster_size": 118,      // Vergleichsobjekte vor Filterung
    "recency_window_months": 12,   // verwendetes Aktualitätsfenster
    "date_span": { "oldest": "2025-08-23", "newest": "2026-08-04" },
    "filters_applied": ["recency=12m", "property_type=etagenwohnung", "elevator"],
    "filters_skipped": ["garden"]   // hätte zu wenige Vergleichsobjekte übrig gelassen
  },
  "location": { "lat": 48.1374, "lon": 11.5755 },
  "typ": "wohnung",
  "property_type": "etagenwohnung"
}

Die Punktschätzungen price und rent sind der Mittelwert über die Vergleichsobjekte, price_range und rent_range das Quartilsband (25.–75. Perzentil). confidence macht transparent, worauf das Ergebnis beruht: wie viele Vergleichsobjekte übrig blieben, welche Filter angewendet wurden und welche übersprungen wurden, weil sonst zu wenige Vergleichsobjekte verblieben wären.

similar_properties listet die Vergleichsobjekte. Ihre Koordinaten (lat, lon) sind auf zwei Nachkommastellen gerundet, also auf ein Raster von etwa 1 km, und geben nur die ungefähre Lage an; eine Straße enthalten sie nicht. Die genaue Lage eines Inserats gibt Somantic zum Schutz der Eigentümer und Bewohner nirgends heraus, siehe Immobilien-API. location ist dagegen der genaue Punkt der angefragten Adresse.

Zu dünne Datenlage liefert keine Zahl. Stützt sich eine Seite auf weniger als 5 Vergleichsobjekte, sind price und price_range bzw. rent und rent_range null. Die Statistik unter price_per_square_meter bzw. rent_per_square_meter und die confidence werden trotzdem geliefert, damit sichtbar bleibt, was gefunden wurde. Behandle beide Felder daher als optional.

Vergleichsobjekte werden zusätzlich nach Aktualität eingegrenzt. Wir versuchen zuerst ein Fenster von 12 Monaten und weiten auf 24 bzw. 36 Monate aus, wenn sonst zu wenige Objekte übrig blieben. recency_window_months nennt das tatsächlich verwendete Fenster, date_span den Zeitraum der einbezogenen Inserate. Ist auch das weiteste Fenster zu dünn besetzt, rechnen wir ohne Zeitfenster und weisen das unter filters_skipped aus.

POST /estimate/quick liefert eine Quadratmeterpreis-Spanne für die Mikrolage – ohne Wohnfläche und ohne weitere Objektangaben. Gedacht für den ersten Schritt eines zweistufigen Bewertungsprozesses: Der Nutzer bestätigt seine Adresse und sieht sofort eine Einordnung, bevor er ein längeres Formular ausfüllt.

Statt des Bewertungsmodells aggregiert dieser Endpunkt die aktiven Inserate des PLZ-Gebiets. Reichen diese nicht aus, weitet er automatisch auf die Gemeinde aus – confidence.basis gibt an, welche Ebene verwendet wurde. Optional übergebene square_meters rechnen die Spanne zusätzlich in absolute Euro um.

Anfrage senden

curl https://www.somantic.net/api/estimate/quick \
  -H "X-API-Key: som_live_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "typ": "wohnung",
    "postcode": "80331",
    "city": "München"
  }'

Beispielantwort

{
  "estimates": {
    "price_per_square_meter": {
      "count": 214, "mean": 9640.0, "median": 9500.0,
      "p25": 8400.0, "p75": 10800.0, "min": 5900.0, "max": 16200.0
    },
    "rent_per_square_meter": { "count": 96, "mean": 23.1, "median": 22.6, ... },
    "price_range": null,      // nur gesetzt, wenn square_meters übergeben wurde
    "rent_range": null
  },
  "confidence": {
    "price": "high",
    "rent": "medium",
    "sample_size": 310,       // ausgewertete Inserate
    "area_size": 310,
    "basis": "plz",           // "plz" oder "stadt" (automatisch ausgeweitet)
    "recency_window_months": 12,
    "date_span": { "oldest": "2025-09-02", "newest": "2026-08-11" },
    "filters_applied": ["recency=12m"],
    "filters_skipped": []
  },
  "area": { "postcode": "80331", "city": "München" },
  "typ": "wohnung",
  "property_type": null
}

Unterstützte Objektarten liefert GET /estimate/property-types, optional eingeschränkt über ?typ=haus bzw. ?typ=wohnung.

{
  "property_types": [
    { "id": "einfamilienhaus",   "label": "Einfamilienhaus",   "typ": "haus" },
    { "id": "doppelhaushaelfte", "label": "Doppelhaushälfte",  "typ": "haus" },
    { "id": "reihenhaus",        "label": "Reihenhaus",        "typ": "haus" },
    { "id": "zweifamilienhaus",  "label": "Zweifamilienhaus",  "typ": "haus" },
    { "id": "mehrfamilienhaus",  "label": "Mehrfamilienhaus",  "typ": "haus" },
    { "id": "etagenwohnung",     "label": "Etagenwohnung",     "typ": "wohnung" },
    { "id": "maisonette",        "label": "Maisonette",        "typ": "wohnung" },
    { "id": "penthouse",         "label": "Penthouse",         "typ": "wohnung" }
    // …
  ]
}

Fehler verwenden Standard-HTTP-Statuscodes mit einem JSON-Body der Form { "detail": "…" }.