Eigenschaften der API
Hier finden Sie eine allgemeine Beschreibung der API-Eigenschaften.
Begrenzungen
Abfrage-Ergebnisse seitenweise liefern
Die Abfrage einer Ergebnisliste ist nur seitenweise möglich. Daher müssen Sie festlegen, wie viele Objekte Sie in einem Request abrufen wollen. Maximal 50 Objekte sind pro Seite möglich. Diese Einschränkung ist aus Auslastungs- und Performancegründen nötig. Um weitere Objekte abzurufen, erstellen Sie einen neuen Request. Eine Sortierung der Objekte ist möglich.
Validierung der Suchabfragen
Alle Suchanfragen im XML-Format werden mit Hilfe eines Schemas definiert. Damit sind bei Beachtung der Schema-Spezifikation nur sinnvolle Element- und Attributkombinationen möglich. Sie sollten gegen das Schema validieren, bevor Sie die API einsetzen. Bei Fehlern werden entsprechende "error codes" geliefert. Weitere Informationen finden Sie in der technischen Dokumentation.
Cachen von Abfragen
Wollen Sie Abfragen zwischenspeichern, dann denken Sie daran, dass ein Objekt in der Zwischenzeit deaktiviert werden kann. Aktualisieren Sie deshalb ihre Daten regelmäßig!
Authentifizierung
Um eine Anfrage an die API zu stellen, führen Sie zuerst ein SessionRequest aus. Um diesen SessionRequest auszuführen benötigen sie zwei Angaben:
- Die Vendor-ID (Scout-ID = Kundennummer des Anbieters) oder eine Börsen-ID legitimiert Sie zum Abrufen der Objekte eines Anbieter/der Börse. Die Vendor-ID erhalten Sie von dem ImmobilienScout24-Kunden. Die Börsen-ID muss beantragt werden (siehe Menüpunkt "Börse anlegen").
- Außerdem benötigen Sie einen Authentifizierungsschlüssel (API-Key). Dieser Schlüssel berechtigt Sie zum Zugriff auf die Objektdaten. Nach Ihrer Registrierung zur API erhalten Sie den Schlüssel automatisch.
Angebotene Bildformate
Bilder werden bei ImmobilienScout24 gehostet und per Link zur Verfügung gestellt.
Folgende Bildformate werden angeboten:
- Kleines Bild für die Ergebnisliste (62x62px) "Result"
- Original Bild vom Anbieter "Original"
- Objekt der Woche Bild "OdW"
- Grosses Bild "Large"
- Bild für Exposé "Expose"
Bei einer Anfrage zur Ergebnisliste sind nur die ersten zwei Bildformate möglich.
Für das Exposé stehen alle fünf Bildformate zur Verfügung.
Statistikfunktion
Die Anzahl der gefundenen Objekte kann über die API ausgeliefert werden. Zum Beispiel können Sie diese Information hinter einen Stadtbezirk schreiben "Wie viele Wohnungen sind in diesem Bezirk verfügbar?" Berlin-Mitte [23].
Angebotsabfragen
Bei der Darstellung der Bundesländer und der Städte/Kreise werden IDs, nicht die ImmobilienScout24-Bezeichnungen verwendet.
Suchabfragen
Folgende Abfragen über die Bestände sind möglich:
- Gesamtbestand eines Anbieters
- Gesamtbestand einer Börse
Diese Bestände können auch nach speziellen Immobilientypen abgefragt werden:
- Wohnung Miete
- Haus Kauf
- usw.
Suchabfragen kombinieren
Sie können bei einer Anfrage zur API mehrere Suchabfragen kombinieren. Folgende Kombinationen werden angeboten:
- Immobilientypen (z.B. Wohnung/Miete, Büros, Anlageobjekte)
- Bundesländer
- Städte/Kreise
Objektaufruf anhand einer Objektnummer
Ein Direktaufruf eines Angebots ist sowohl mit der Anbieter-Objektnummer, als auch mit der Scout-Objekt-ID möglich.
Umkreissuche
Eine Umkreissuche liefert Objekte, die innerhalb eines angegebenen Kreises um eine PLZ oder Strasse liegen. Dazu wird eine Anfrage an die API geschickt, mit der die Adresse in einen Geocode umgewandelt wird. Mit dem Geocode führen Sie die Umkreissuche aus.
Wenn ein Ort eingegeben wird, den es mehrmals gibt, liefert die API eine Liste möglicher Geocodierungen. Sie setzen diese Liste ein, so dass der Benutzer Ihres Internetauftrittes den richtigen Ort wählen kann.
Geo-Koordinaten
Wenn Sie die geoX- und geoY-Koordinaten bei einem Exposé-Aufruf erhalten möchten, müssen Sie die Adresse des Objektes vollständig freigeben. Stellen Sie dies in der Online-Objektverwaltung ("AngebotsManager") oder in Ihrer Import-Software unter "Adresse vollständig anzeigen" ein.
Ergebnisliste
Filtern/Sortieren
Sie können die Ergebnisliste nach mehreren Kriterien sortieren lassen, z.B. zuerst nach Preis, dann nach Wohnfläche.
- Anzahl der Objekte pro Seite ist ein Parameter in der Abfrage:
-Werte: 3- 50
-Aufsteigend / Absteigend (Nachfrager kann bei Sortierfeldern absteigend UND aufsteigend sortieren. Die Eingabe geschieht pro Sortierkriterium: Preis absteigend, Zimmerzahl aufsteigend)
- Sortierungen können nicht über Boolean-Werte erfolgen. Zudem müssen alle Kriterien groß geschrieben werden.
Frei definierbare Felder
Es werden Ihnen bei der Objekteinstellung drei neue Felder angeboten, die Sie in der API als Suchfelder einsetzen können. Den Inhalt dieser Felder können Sie frei definieren. Die einzige Vorgabe ist, dass es ein Textfeld mit max. 16 Zeichen ist (zugelassene Zeichen: 0-9, a-z, A-Z).
Diese drei Suchfelder stehen sowohl Kunden, die ihre Objekte online einstellen, als auch Kunden, die ihre Objekte per Software übertragen, zur Verfügung. Die Felder werden nicht beim ImmobilienScout24-Exposé, sondern nur in Ihrem, mit der API erstellten Exposé, angezeigt. Sie können die Felder auch nur als Suchkriterium verwenden.
Was ist besonders an diesen Feldern?
Hiermit können Sie Suchkriterien oder Felder definieren, die bei der ImmobilienScout24-Suche nicht angeboten werden (z.B. "mit Keller").
Exposébestandteile
Wir empfehlen Ihnen folgende Exposébestandteile einzubauen:
ScoutReport - Zählung von Aufrufen und Kontakten
Da ImmobilienScout24 mit der API nur Daten und keine Links ausliefert, können die Aufrufe ("Ergebnisliste angezeigt", "Objekt in Suche enthalten", "Exposéaufruf") für den ScoutReport des Anbieters nicht gezählt werden.
Weitere Besonderheiten
Suchkriterium "IncludeDivisible"
Das Suchkriterium "IncludeDivisible" hat die Besonderheit, dass es nicht allein benutzt werden kann. Es benötigt immer "siteArea" oder "netArea" je nach Immobilientyp.
"IncludeDivisible" bedeutet, dass auch Immobilien die "teilbar" sind mit in die Suche eingebunden werden sollen.
Damit ist nicht gemeint, dass nur nach teilbaren Immobilien gesucht wird.
Der Wert "teilbar ab" wird bei "InlcudeDivisible = true" mit in die Suche der angegebene Quadradmeterzahl "von - bis" integriert.
Ein Beispiel:
Sie suchen eine Gewerbefläche von 600-800qm. Benutzen sie nun nur das Suchkriterium "siteArea", bekommen sie alle Immobilien zwischen 600 und 800qm angezeigt.
Benutzen Sie nun auch "includeDivisible" werden auch Immobilien angezeigt, die z.B. ab 700qm teilbar sind.
Probieren Sie dies einfach mal bei der normalen Immobilienscout24-Suche aus, die Logik ist die gleiche.
Preis auf Anfrage
Wenn Sie im Objekteditor im ScoutManager die Checkbox "Preis auf Anfrage" markiert haben, wird im Result der API der Wert 0 als Kauf- oder Mietpreis ausgegeben. Somit müssen Sie diese Buisness-Logik in Ihrer Anbindung so umsetzen, das bei einem Kauf- Mietpreis von 0 ein "Preis auf Anfrage" ausgegeben wird.
Der Marktführer: Die Nr. 1 rund um Immobilien
