FAQs
General
Is there an overview of all fields that the Offer REST-API can return?
Please see the XML schema here.
Authentication
I'm having trouble with the authentication? I get 401.
If your request is rejected with status code='401' and you receive:
1 2 3 | |
Energy certificate 2014
Are the new API fields mandatory?
No. The fields according to the energy certificate 2014 are no mandatory fields.
Is it possible to upload (if exists) the energy certificate as a file to the expose and leave the fields empty?
Yes and no. You can upload the energy certificate as a file, but that is not enough to be legally secured.
Is it necessary to use the energycertificate fields?
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
Why is the order after the image upload incorrect?
The reason can be that you uploaded every image as a cover picture ("titlePicture"). Consequently is always the latest uploaded image on top.
How to get access to the original image files.
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
How can I delete and update individual attachments (images belonging to real estate objects) with the PHP-SDK?
It is documented in the SDK-Wiki on this page: https://github.com/ImmobilienScout24/restapi-php-sdk/wiki/Objekte-exportieren
Can I afterwards update the *external* ID from a real estate object?
No
Is it possible 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.
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.
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 following elements:
Later we update this files, but only transfer the changed elements:
A: Not covered elements are set as NULL. It is important 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.
Can/should strings be embedded in [CDATA]-Tags?
No, CDATA and HTML are not supported. For line breaks, please use { } at XML.
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?)
here you can find the schema where the contact with ID is referenced: https://rest.immobilienscout24.de/restapi/api/offer/v1.0/?_wadl&_type=xml. The XML-schema for contact is here: https://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.
How can I call/filter the from us provided "old" data? (for updating)
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.
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?
No, one transfer for one contact/real estate object.
Should the element already start with "ext-" or is that an automatic written prefix?
The "-ext" should be specified by you.
Can/Must the externalId's from contact and real estate object match?
No, they are independent. The linkage takes plays in background over the scout object ID.
The customer got a transfer protocol after the transfer with FTP-Importer yet. Does it exist for the REST-API too?
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.
Is there a request to get all geo-data or cities or all real estate objects from a realtor?
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.
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?
See the tutorial, here. Please use one of our SDKs or one of the CMS plugins, since they contain all necessary functionalities.
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?
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.
To what refers the suffix "me" at the three-legged oAuth?
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.
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 "normal" requests (without authentication) don't work anymore. What's the problem?
Please check whether the URL fits allow_fopen.
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?
The error messages point to that the request token was fetched successfully. 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
How to get the bigger images? I only get the small one with a size of 60x60
Within the expose request, 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:
No, that's not possible. Upon contacting the expose owner or realtor, ImmoScout24 always sends the email. We therefore provide the contact api.
This has following reasons: The realtor as well as the demander receive the e-mail. The address of the sender for contact mails from ImmoScout24, is at the known e-mail providers on the white list, consequently there are no spam problems.
Furthermore, we report the number of contact requests for the realtors in the ScoutReport so that the realtors can scale their marketing strategy.
Is there a possibility to get the deposited e-mail address from an expose?
How can I show video-attachments which are uploaded as a streaming video?
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
Which are the correct names for real estate types like "Wohnen auf Zeit/Möblierte Wohnungen" and "Anlageobjekte"?
An overview of the supported real estate types you can find here.
Is it possible to perform a REST-API request with my own object id instead of the ImmobilienScout24 object id?
Within the search and expose APIs, it's not possible. Within the Import-Export-API (documentation) it's possible.
Is it possible to do a valid search request to the API and read the possible values for each parameter mechanically?
No.
Is it possible to search through the whole inventory of IS24?
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".
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!
To search for all AppartmentRent in Berlin you may 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")
Is there three-legged oAuth at "Börsen"?
There is no three-legged OAuth at "Börsen", the information of groupid and parameter channel is enough.
What is a Group ("Börse") and how can I create one?
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 a short period of time, 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.
Geo/GIS
I get at quarter: "unknown". Why?
The geo hierarchy for addresses abroad doesn't support "quarter". The lowest level is city/district in the API "city".
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.
While doing radius search, you only find real estate objects which are geocoded successfully, the search by geo hierarchy prevents that. See the search api documentation with resource "region", here. The documentation for obtaining the geo hierarchy ids can be found, here.
How to get geo location (lat/lng) from a real estate object?
In result list as well as in the expose you can find the geo location ("wgs84Coordinate").
Are there reference data about your regions (country-region-city-quarter) as a static CSV file?
No, it doesn't exist, because the geo hierarchy changes through GIS-updates. This includes many yearly changes in regions, districts and communes. We aim for quarterly updates according to pure geo data. Consequently it's worth it to fetch the data from the REST-API.
The radius search abroad doesn't know any city.
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). The API behaves 1:1 to the web.