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

Ein flexibler GraphQL-Endpunkt über aggregierte deutsche Inserate für Häuser und Wohnungen – von Immowelt, Immonet, Kleinanzeigen, Ohne Makler und Immobilienscout24. 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, wohnung jetzt, 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.0,           // geschätzte monatliche Kaltmiete (€)
    "price": 712500.0,        // geschätzter Kaufpreis (€)
    "similar_properties": [ ... ]
  },
  "location": { "lat": 48.1374, "lon": 11.5755 },
  "typ": "wohnung"
}

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