Get Started

FAQ

We answer the common questions here. Please read through these questions before using other ways of supporting.

Energy certificate 2014

Q: Are the new API fields mandatory?

A: No. The fields according to the energy certificate 2014 are no mandatory fields.

 

Q: Is it possible to upload (if exists) the energy cerftificate as a file to the expose and leave the fields empty?

A: Yes and no. You can upload the energy certigicate as a file, but that is not enough to be legally secured.

 

 

Q: We cannot handle the swith to the API up to the 1st may. Does that mean that we are not allowed to publish our real estate objects?

A: You can transfer the data according to the energy certificate in the expose free text field "Sonstiges". The advantage of transfering the data in the corresponding energy certificate fields is, that the EnEv fields are grouped in the expose and we show a graph in the expose.

 

Import-Export-API

Q: Why is the order after the image upload incorrect?

A: The reason can be that you uploaded every image as a cover picture ("titlePicture"). Consequently is always the latest uploaded image on top.

 

Q: How to get access to the original image files.

A: You only need to shorten the picture-URL, that you get as a response from GET ATTACHMENT request as followed:

http://picture.immobilienscout24.de/pic/orig02/N/211/828/677/211828677-0.jpg/ORIG.

 

Q: How can I delete and update individual attachments (images belonging to real estate objects) with the PHP-SDK?

A: It is documented in the SDK-Wiki on this page: https://github.com/ImmobilienScout24/restapi-php-sdk/wiki/Objekte-exportieren

 

Q: Can I afterwards update the *external* ID from a real estate object?

A: No.

 

Q: Is it possbile to perform a *real* deletion of a real estate object/expose? That means not to deactivate, but to remove completely out of the realtors offer list.

A. No. One reason therefor: After a deletion it is not possible to request an evaluation of the realtor for this real estate object at the potential buyer.

 

Q: What happens if I don't send all elements at the PUT REALESTATE request?

We transfer real estate object files which contain for example the follwoing elements: <externalId>ext-heim0815</externalId> <title>Irgendwas</title> <petsAllowed>YES</petsAllowed> <counselingAvailable>NOT_APPLICABLE</counselingAvailable> <leisureActivitiesAvailable>YES</leisureActivitiesAvailable>.

Later we update this files, but only transfer the changed elements: <externalId>ext-heim0815</externalId> <title>Irgendwas DAZU</title> <counselingAvailable>YES</counselingAvailable>.

A: Not covered elements are set as NULL. It is importent to send all elements at the PUT REALESTATE request, although nothing changed at some elements. Because we don't know whether you want not to change or to delete the value of one element.

 

Q: Can/should strings be embedded in [CDATA]-Tags?

A: No, CDATA and HTML are not supported. For line breaks, please use { } at XML.

 

Q: The <contactId> does not appear in the XML-schema. Can that be specified multiple in one sequence? (Can I put multiple contacts to one real estate object?)

A: You can find the schema where the contact with ID is refenced: http://rest.immobilienscout24.de/restapi/api/offer/v1.0/?_wadl&_type=xml. The XML-schema for contact is here: http://rest.immobilienscout24.de/restapi/api/account/v1.0/?_wadl&_type=xml. The connection contact-real estate object is 1-n: it is not possible to specify multiple contacts to one real estate object. Surely you can reference one contact in multiple real estate objects.

 

Q: How can I the call/filter the from us provided "old" data? (for updating)

A: Here is an overview of the relevant requests of the import/export API. With the request GET http://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/{username}/realestate you get all your real estate objects as a list.

 

Q: Can I combine more contact data or exposes in one XML-file or do I have to start the transfer for every single contact/real estate object?

A: No, one transfer for one contact/real estate object.

 

Q: Should the <externalId> element already start with "ext-" or is that an automatic written prefix?

A: The "-ext" should be specified by you.

 

Q: Can/Must the externalId's from contact and real estate object match?

A: No, they are independent. The linkage takes plays in background over the scout object ID.

 

Q: The customer gets a transfer protocol after the transfer with FTP-Importer yet. Does it exist for the REST-API too?

A: The customers don't get a transfer protocol, because the real estate objects are edited separate and the API puts out errors/success messages in a form which is readable for machines. The software provider can show them in the software or editing screen. A summary afterwards doesn't exist, but is received as a demand und we have to see what can be done.

Realtors website: access to real estate objects of a certain realtor

 

NEW: There is a Tutorial for this Usecase.

 

Q: Is there a request to get all geo-data or cities or all real estate objects from a realtor?

A: No. The REST Search API can only search within one real estate type at a time. You would have to call all real estate types, separate. To get all regions, you have to search with the geo-id, for example "1276" stands for Germany. Documentation: Geohierarchy/Continent.

 

Q: We would like to develop a website for a customer where one can search for the customers IS24-real estate objects. Which procedure do we have to choose?

A: See the tutorial, here. Please use one of our SDKs or one of the CMS plugins, since they contain all necessary functionalities. Here's an overview.  

 

Q: The request http://rest.immobilienscout24.de/restapi/api/search/v1.0/search/region?realestatetype=apartmentrent&geocodes=1276&channel=hp&username={your username} requires the username. Where can I find my username?

A: The username with that the ImmobilienScout24-user (e.g. the customer) logs in. Additionally to the username, your customer has to activate the access from your "system" to his IS24-account over three-legged oAuth.

 

Q: Wo what refers the suffix "me" at the three-legged oAuth?

A: The suffix "me" refers to the username. The currently logged in user (in your case: your customer who logged in over three-legged oAuth) is going to be authenticated und then you have access with GET search to his real estates.

 

Q: I develop a website and use the API resource that filters real estate objects from a realtor. Before, I have to authenticate. Although I cleared the mysql database and changed the callback url, it doesn't work. Still the "normale" requests (without authentification) don't work anymore. What's the problem?

A: Please check whether the URL fits allow_fopen.

 

Q: I always get the error message "Es ist ein Fehler aufgetreten: Das gelieferte Token ist ungültig, abgelaufen oder wurde bereits verwendet. Bitte wiederholen Sie den Vorgang in der Fremdapplikation." or after new registration the message code "ERROR_COMMON_INTERNAL_SERVER_ERROR". What's the problem?

A: The error messages point to that the request token was fetched succesfully. Furthermore it was used to fetch the access token, but that caused an error. Most probable the oAuth header was built wrong. How to do right, you find something here.

Expose

 

Q: How to get the bigger images? I only get the small one with a size of 60x60.

A: Within the expose requst, we hand out several pre-scaled image resolutions.  You can cut off the picture url by deleting everything behind "ORIG" in order to obtain the original size:

<url scale="SCALE_540x540" href="http://picture.preview-is24.de/pic/orig04/N/103/343/907/103343907-0.png/ORIG/>

 

Q: Is there a possibility to get the deposited e-mail address from an expose?

 
A: No, that's not possible. At contacting, Immobilienscout24 alwasy sends the email. We therefore provide the contact api. This has following reasons: The realtor as well as the demander get the e-mail. The address of the sender for contact mails from IS24, is at the known e-mail providers on the white list, consequently there are no spam problems. We report the contact requetsts for the realtors in the ScoutReport with that the realtors can scale their marketing strategy.

 

Q: How can I show video-attachments which are uploaded as a streaming video?

A: With a request to http://home.immobilienscout24.de/videoservice with the "videoId" from attachment data from expose you get an URL existing of a video player with the parameter "playlist". Because the customer wants a nice play more than the default one, I extract the URL of the playlist (the value for the parameter "playlist") and send a request for the playlist. The playlist which arrives, is a XML file in which the URL to the FLV file is. This one can I view in my own player. Different as in the old API, I fetch the data from the video service and the playlist not in JavaScript and Ajax but rather in PHP.

Search

 

Q: Which are the correct names for real estate types like "Wohnen auf Zeit/Möblierte Wohnungen" and "Anlageobjekte"?

A: An overview of the supported real estate types you can find here.

 

Q: Is it possible to perform a REST-API request with my own object id instead of the immobilienscout24 object id?

A: Within the search and expose APIs, it's not possible. Within the Import-Export-API (docu) it's possible.

 

Q: Is it possible to do a valid search request to the API and read the possible values for each parameter mechanically?

A: No.

 

Q: Is it possible to search through the whole inventory of IS24?

A: Yes, if you got the right permissions. Please fill out the email form for applying access on the getting-started page, following the instructions for "content partner".

 

Q: I have a customer key (API Key), customer secret (API Secret) and also a oAuthKey and oAuthSecret. How to build a request to get for example all AppartmentRent's in Berlin? I want to fetch the data in json-format dynamically and handle them in processing!

A: To search for all AppartmentRent's in Berlin you preferably use http://rest.immobilienscout24.de/restapi/api/search/v1.0/region?realestatetype=apartmentrent&geocodes=1276003001. At "geocodes", the 1276 means Germany, 003 region Berlin and 001 city Berlin.

Groups ("Börsen")

 

Q: What is a Group ("Börse") and how can I create one?

A: The "Börse" is a group of customers in the database. The creation of a "Börse" is simple: send an e-mail to service@immobilienscout24.de. Required are a customerID-list of participants and a short name for the "Börse". Within 24h, you'll get the "Börsennummer" (in API and following text: groupid) by mail. After that, the participants have to publish their real estate objects in this group. It works with handling in the login area at immobilienscout24.de ("ScoutManager") as well as by REST-API (request "publish", documentation). Adding/Deleting customers has to be done by our support, (email us:  service@immobilienscout24.de). We have a tutorial for using the "Börse" functionality for displaying objects on a website, here.

 

Q: Is there three-legged oAuth at "Börsen"?

A: There is no three-legged oAuth at "Börsen", the information of groupid and parameter channel is eneough.

Geo/GIS-Stuff

I get at quarter: "unknown". Why?

A: The geohierarchy for addresses abroad doesn't support "quarter". The lowest level is city/district in the API "city".

 

Q: I don't get all real estate objects. My customer published 10 real estate objects to all channels, but I only get 8 of them although doing requests for all real estate types sequentially.

A: While doing radius search, you only find real estate objects which are geocoded successfully, the search by geohierarchy prevents that. See the search api documentation with ressource "region", here. The documentation for obtaining the geohierarchy ids can be found, here.

 

Q: How to get geo location (lat/lng) from a real estate obejct?

A: In result list as well as in the expose you can find the geo location ("wgs84Coordinate").

 

Q: Are there reference data about your regions (country-region-city-quarter) as a static CSV file?

A: No, it doesn't exist, because the geohierarchy changes through GIS-updates. This includes many yearly changes in regions, districts and communes. We aim for quarterly updates according to pure geodata. Consequently it's worth it to fetch the data from the REST-API.

 

Q: The radius search abroad doesn't know any city.

  • A: Basically we don't offer radius search for real estate objects abroad. Requirement for that case would be the worldwide geocoding (and also buying address data). You can find our web search abroad here. The API behaves 1:1 to the web.

General

 

Q: Is there an overview of all fields that the REST-API can return? Preferably there should be an overview of alle existing fields.

A: For that we offer an XML schema.