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 netto zzgl. 19% MwSt.

Ein flexibler GraphQL-Endpunkt über aggregierte deutsche Inserate für Häuser und Wohnungen – von Immobilienscout24, Immowelt, Kleinanzeigen, Ohne Makler, Immobilien.de, Wohnung-Jetzt und weiteren Portalen. Jedes Inserat wird mit dem fairen Schätzwert unseres SOM-Modells (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.

Unterstützte Plattformen

In Arbeit: meinstadt.de, regionalimmobilien, Sparkasse Immobilien.

Verfügbare Abfragen

Alle Abfragen akzeptieren die Argumente filters, page, per_page (max. 100), order_by (Feldname für aufsteigend, - davor für absteigend, z. B. "-uptime_date") sowie equity_percentage, interest und repayment zur Anpassung der Cashflow- und ROI-Berechnung. is_active wird automatisch auf true gesetzt, sofern nicht anders angegeben.

Beispielabfrage

{
  all_appartments(
    filters: { city: "München", price_lt: 600000, square_meter_gt: 50 }
    per_page: 5
    order_by: "roi"
  ) {
    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", spider: "kleinanzeigen" }
  ) {
    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", spider: "kleinanzeigen" }
  ) {
    edges { node { uptime_date url square_meter price } }
  }
}

{
  all_houses(
    order_by: "-price"
    per_page: 20
    page: 1
    filters: { is_active: true, action: "kaufen", location: "bl-baden-wuerttemberg", spider: "immowelt" }
  ) {
    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
        spider
        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
        spider
        title
        location
        city
        state
        zipcode
        price
        price_per_square_meter
        square_meter
        year_of_construction
        uptime_date
      }
    }
  }
}

{
  all_appartments(
    order_by: "som_model_percentage"
    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: "-roi"
    per_page: 25
    equity_percentage: 0.2
    interest: 0.035
    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
      }
    }
  }
}

Liefert eine sofortige Miet- und Kaufpreisschätzung für jede deutsche Adresse, basierend auf einem Self-Organizing-Map-Modell, das mit Live-Marktdaten trainiert wurde. Sende ein POST an /estimate mit den Objektdaten.

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": [ ... ]
  },
  "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.

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 über den gesamten Bestand 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 SOM-Modells 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": "…" }.