Der Marktführer: Die Nr. 1 rund um Immobilien
Immobilienwelten
- 26.05.2012
- Willkommen! Anmelden oder neu registrieren.
XML-Tutorial
Dieses Tutorial beschreibt die generelle Kommunikation mit der Immobilienscout24-API.
Es werden Beispiele für Requests zur IS24-Schnittstelle aufgezeigt. Dieses Tutorial können Sie verwenden, egal mit welcher Programmiersprache Sie die Umsetzung durchführen wollen. Der hier beschriebene XML-Request muss dann mit der entsprechenden Programmiersprache aufgebaut und an die API geschickt werden. Zurück bekommen Sie ein XML-Dokument, das Sie mit Ihrer Programmiersprache auswerten müssen.
Bemerkung: Zum Testen der API-Anbindung steht eine Test-Vendor-ID zur Verfügung:
6687764
SESSION ERSTELLEN
Um eine Abfrage auf Objektdaten eines Anbieters oder einer Börse zu machen, müssen Sie zuerst ein SessionRequest mit Ihrer Vendor-ID und dem API-Key erstellen. Diese schicken Sie dann per http-Post an die URL:
http://api.immobilienscout24.de/api/xmlhttp/SessionService
CreateSessionRequest für einen Anbieter:
CreateSessionRequest für eine Börse:
Wenn Sie eine der beiden Anfragen gestellt haben, bekommen Sie so ein Result zurück:
Hinweis: Die SessionId ist immer unterschiedlich. Sie können dieses Result so nicht verwenden.
Als Ergebnis haben Sie nun die vier Service-URLs bekommen, die Sie für die weiteren Anfragen benötigen. Je nachdem, was Sie abrufen wollen, müssen Sie die Anfrage an die richtige Service-URL stellen. Am häufigsten werden Sie wohl den RequestService benötigen.
EINFACHE ABFRAGE
Einfache Abfrage einer Ergebnisliste aller Miet-Wohnungen im Bestand des Anbieters/Börse. Ausgabe der ersten Seite mit 50 angezeigten Objekten (wenn vorhanden), absteigend nach der Überschrift sortiert.
Die Anfrage wird an den RequestService, wie oben beschrieben gestellt.
Denken Sie daran zuerst diesen Service mit dem CreateSessionRequest erstellt zu haben.
Als Ergebnis bekommen Sie alle Mietwohnungs-Objekte des Anbieters als XML zurück.
Hier sehen Sie einen kleinen Ausschnitt eines möglichen Results:
Sie bekommen die Grundinformationen der Immobilie als XML zurück.
Im Detail bedeutet dieses Result folgendes (von oben nach unten): Zusätzlich zu Ihren Informationen, wie viele Objekte Sie abrufen und welche Seite Sie haben wollten, erhalten Sie die Gesamtanzahl der Objekte "numberOfMatches" und der Seiten "numberOfPages".
Die ResultLine-Nummer zeigt, um welches Objekt es sich handelt. (Hier 0-49 bzw. bei 33 Objekten 0-32 Es wird also ab 0 gezählt.)
Das nächste Element "AppartmenRentProxy" umfasst nun das eigentliche Mietobjekt. Die Attribute und Elemente innerhalb diesem, beschreiben sich von selbst. Sollten Sie einmal nicht wissen, was das Element/Attribut bedeutet, schauen Sie in der technischen Dokumentation nach.
Folgende Aufrufe von Immobilientypen sind möglich:
- AppartmentBuyQuery (Kauf-Wohnung)
- AppartmentRentQuery (Miet-Wohnung)
- GastronomyQuery (Restaurant)
- HouseBuyQuery (Kauf-Haus)
- HouseRentQuery (Miet-Haus)
- HouseTypeQuery (Typenhäuser)
- IndustryQuery (Industrieobjekt)
- InvestmentQuery (Investment)
- MiscQuery (Sonstiges Gewerbe)
- OfficeQuery (Büro)
- SiteQuery (Grundstücke)
- StoreQuery (Geschäft/Laden)
- WazQuery (Wohnen auf Zeit)
Weitere Informationen finden Sie in der request.xsd
Hinweis zur Sortierung:
Sie können so viele Sortierungen wie Sie benötigen einfügen, z.B.:
Es wird zuerst nach dem ersten Eintrag sortiert, dann nach dem zweiten usw. Nach Boolean-Werten kann nicht sortiert werden. Zudem ist zu beachten, dass der Name des Suchkriteriums immer mit einem Großbuchstaben beginnen muss.
Hinweis zu den Seiten:
Um die zweite Seite anzuzeigen, müssen Sie einen erneuten Request stellen mit pageNumber="1" bzw. pageNumber="2" usw.
Wenn Sie beispielsweise nur 20 Objekte auf einer Seite der Ergebnisliste wünschen, ändern Sie den Wert von „pageSize“ entsprechend. (pageSize="20")
Abfrage von Geo-Informationen
Also nächstens soll diese Abfrage etwas spezieller werden. Es sollen nicht alle Mietwohnungen ausgegeben werden, sondern beispielsweise nur die Mietwohnungen in Berlin-Mitte. Um diesen Request auszuführen, benötigen Sie erstmal die Immobilienscout24 internen ID's für Kontinent, Land, Bundesland, Stadt und Stadtteil/Bezirk. Deshalb muss erst ein GeoRequest ausgeführt werden. Schicken Sie Ihren Request an den GeoInfoService, der am Anfang erstellt wurde.
Kontinent-Request:
Sie bekommen nun folgendes Result:
Sie sehen hier die Ausgabe der Kontinente mit der Immobilienscout-Nummer dafür. Für weitere Requests wird diese Nummer dann benötigt, je nachdem über welchen Kontinent Sie die Anfrage stellen möchten.
Die weiteren Requests werden nun aufgeführt, allerdings ohne Result. Diese Daten werden dann gleich für eine speziellere Abfrage der Mietwohnungen in Berlin-Mitte benötigt.
Land-Request für Europa:
Bundesland-Request für Deutschland:
Stadt-Request für das Bundesland Berlin:
Stadtteil/Bezirk-Request für Berlin:
Das Result dieses Requests liefert nun die ID des Berliner Stadtbezirks Mitte:
Die uuid's die bei jeder Anfrage angegeben wurden, kamen immer aus dem entsprechenden Result der vorherigen Anfrage.
Wie Sie vielleicht bemerkt haben, werden die uuid's jedes Mal verfeiert. An der uuid=1276003001 ist immer noch zu Erkennen, z.B. welcher Kontinent (1) oder welches Land (1276) sich dahinter verbirgt.
Das Attribut "name" ist optional.
Hier noch ein Tipp: Cachen Sie die Geo-Informationen z.B. in einer eigenen Datenbank, dann müssen Sie nicht jedes Mal abgerufen werden. Dies führt zu einer Performance-Steigerung.
Die Geo-Informationen werden nur selten aktualisiert.
Nun haben Sie die Grundlage geschaffen, um sich alle Mietwohnungen in Berlin-Mitte ausgeben zu lassen. Senden Sie nun folgende Anfrage an den RequestService:
Hinweis: Sie müssen bei so einer Anfrage immer alle Geo-Informationen die höher liegen mit angegeben. D.h. bei diesem Beispiel zusätzlich zum "quarter": city, region, country und continent.
Als Ergebnis bekommen Sie die Mietwohnungen in Berlin-Mitte. Wenn Sie mit der Test-Vendor-ID arbeiten, wird eine Wohnung im Result zurückgegeben.
Sie können bei diesem Request auch Regionen, Stadtteile usw. kombinieren, wie Sie wünschen. Wollen Sie beispielsweise zu den Miet-Wohnungen in "Berlin-Mitte" noch alle Miet-Wohnungen im Bundesland "Bayern" angezeigt bekommen, könnte Ihr Request so aussehen:
Wie Sie sehen sind hier beliebige Anfragen mit nur einem Request möglich. Noch ein Beispiel dazu: Alle "Miet-Wohnungen" in "Berlin-Mitte" und alle "Kauf-Häuser" in "Bayern"
Es ändert sich somit nur die Abfrage nach dem Immobilientyp (HouseBuyQuery).
Umkreissuche
Bleiben wir erstmal noch bei den Abfragen mit Einschränkungen der Geo-Informationen. Bisher ist ein Aufruf mit einer genauen Angabe von Orten oder Stadtteilen erfolgt. Es gibt noch eine weitere Möglichkeit Objekte nach bestimmten Gebieten abzurufen und zwar mit der Umkreissuche.
Bei der Umkreissuche geben Sie eine Postleitzahl an (optional kann auch eine Strasse mit angegeben werden street="Straße") und einen Umkreis in km von diesem Punkt aus. In diesem Umkreis werden alle Objekte ausgeliefert.
Bevor die explizite Suche nach Objekten erfolgt, muss zuerst ein Geo-Code des Ausgangspunkts für den Umkreis erstellt werden.
Hier ein Beispiel für die Postleitzahl "10179" aus der Stadt "Berlin".
Als Result bekommen Sie nun zurück:
Nun können Sie auf Grundlage der Geo-Koordinate eine Suchanfrage stellen: (Umkreis von 5km):
Als Result bekommen Sie nun alle Mietwohnungen, die 5km um diese Postleitzahl herum liegen.
Abfrage mit Immobilieneigenschaften
Neben den Abfragen von bestimmten Immobilien einer Region kann auch zusätzlich nach gewissen Immobilieneigenschaften gefiltert werden.
Die folgende Abfrage liefert Ihnen alle Immobilien aus Ihrem Bestand oder einer Börse mit den Eigenschaften:
- Zimmer: 4 bis 5
- Quadratmeterzahl: 80qm bis 90qm
- Kaltmiete: 400 Euro bis 500 Euro
- Balkon: ja
- Garten: nein
Als Ergebnis bekommen Sie die Immobilien zurück, die diesen Angaben entsprechen. Die vollständige Liste von Immobilieneigenschaften, die Sie hier abfragen können, finden Sie in der technischen Dokumentation (Eigenschaften sind Abhängig vom Immobilientyp):
Weitere Informationen finden Sie in der request.xsd
Die Kombination von Immobilieneigenschaften und GEO-Informationen bei einer Abfrage ist möglich.
Hinweis: Wenn bei einer Immobilie z.B. die Parkplatzanzahl wie folgt abgefragt wird:
<noParking lower="0" upper="125"/>
es für die Immobilie aber gar keine Angabe zu den Parkplätze gibt, bekommen Sie eine leere Ergebnismenge.
Ist eine Abfrage aller Parkplätze gewünscht, lassen Sie diese Zeile in der Query weg. Gleiches gilt für alle Query"s die eine Min/Max-Anfrage unterstützen, insbesondere totalArea und noParking.
API-FELDER
Wenn Sie die API nutzen haben Sie zusätzlich drei Felder, die Sie für ihr Angebot füllen können. Über diese Felder lässt sich auch eine Abfrage generieren.
In diesem Beispiel werden Objekte gesucht, die einen Pool und eine Sauna besitzen (beides Eigenschaften, die es so bei Immobilienscout24 nicht gibt).
Wenn Sie den "searchField"-Inhalt leer lassen (<searchField1></searchField1> bzw. <searchField1/>), werden alle Immobilen angezeigt, die einen leeren Eintrag im "searchField1" haben.
Dies kann sinnvoll sein, wenn Sie z.B. Objekte suchen, die keinen Pool haben.
ABRUF EINES EXPOSÉS
Um ein Expose der gefunden Immobilien aufzurufen, haben Sie zwei Möglichkeiten. Entweder Sie rufen das Objekt über die Immobilenscout24-Objekt ID (uuid) auf:
Oder Sie rufen das Objekt mit Ihrer eigenen Objekt-ID auf, die Sie beim Einstellen des Objektes vergeben haben.
Der Bildtyp "pictureType" gibt an, welche Größe das Bild haben soll. Es sind fünf Varianten möglich:
- 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"
Alternativ kann das Expose auf der Immobilenscout24-Seite angezeigt werden, rufen Sie dazu die Immobilienscout24-Seite auf und hängen an die URL die uuid.
http://www.immobilienscout24.de/44407298
Hinweis: Wenn Sie das Expose auf Immobilienscout24 aufrufen, muss es dort auch veröffentlicht sein.
EXPOSÉ PER E-MAIL WEITERLEITEN
Die API bietet die Funktion "Exposé per E-Mail weiterleiten". Dazu schicken Sie Ihre Anfrage an den "ContactService", die URL, die vom SessionService (siehe Anfang des Tutorials), erstellt wurde.
Bei einem MailAFriendRequest können Sie eine bestimmte Immobilie als Link zu Immobilienscout24 per E-Mail automatisch an jemanden schicken lassen. Sie geben Sender und Empfänger E-Mail-Adresse an, die Immobiliennummer und optional einen Kommentar.
Der Empfänger bekommt nun eine Mail mit dem Link zur Immobilie auf Immobilienscout24. Diese muss dort auch veröffentlicht sein.
Sie bekommen als Result einen Status zurück, ob die E-Mail erfolgreich versendet wurde.
STATISTIKEN
Eine besondere Funktion ist der Abruf der Bestände in einem bestimmten Bundesland/Stadt/Bezirk. Diese Statistiken lassen sich einfach realisieren. Schicken Sie die Anfrage an den GeoInfoService.
Anzahl der Mietwohnungen in den Stadtbezirken von Berlin:
Anzahl der angebotenen Kauf-Häuser in den Städten Nordrhein-Westfalens:
Das Result sieht ausschnittsweise dann so aus:
Es gibt somit drei Kauf-Häuser in Oberhausen und keins in Olpe.
PING-AUFRUF
Um eine Session länger als 15 Minuten zu erhalten, müssen Sie einen PingSessionRequest stellen. Dies gilt nur, wenn in dieser Zeit Interaktion mit der Api durchgeführt wurde. chicken sie diesen Request an den SessionService und die Session ist weitere 15 Minuten gültig.
ALLGEMEINER HINWEIS ZUM SCHLUSS:
Wenn Sie bei den Abfragen Umlaute verwenden, konvertieren Sie die Anfragen immer in UTF-8, bevor Sie an die API geschickt werden!
Zu Testzwecken können Sie die hier angegebenen XML-Requests als String an die API schicken.
Beispiel PHP:
