Developer

These FAQ for developers shall help to find answers to most asked questions.

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:

<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<message> <messageCode>ERROR_COMMON_AUTHENTICATION_REQUIRED</messageCode>
<message>Authentication is required for this operation. [ERROR MESSAGE: Invalid signature for signature method HMAC-SHA1]</message></message> </common:messages>

Check that it complies with the following rules:

all OAuth parameters set in the signature base string must be set in the Authorization header
the oauth_signature must not be part of the signature base string, but it must be part of the Authorization header
except the oauth_signature the Authorization header must not contain more/other OAuth parameters than the signature base string.

Following these rules is necessary as our server recalculates the signature base string and the signature to validate the request. Note that the sequence of the parameters in the Authorization header is not relevant for the server-side recalculation. Check, that for POST and PUT requests, when data is sent in the body, the correct Content-Type header is set to application/xml.

Also check whether the Password has been changed in between. That will invalid the token and you have to do a new authentication for getting a new valid token.

I'm getting "Invalid signature for signature method HMAC-SHA1" during Authentication prozess.

If your request is rejected with status code='401' and you receive:

<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<message><messageCode>ERROR_AUTHENTICATION_REQUIRED</messageCode>

     <message>Invalid signature for signature method HMAC-SHA1</message>

 </message> </common:messages>

Then check if you did the URL-decoding of the response value oauth_token_secret in step 1 and step 3 like it is described here.

OAuth1 Authentication with python

The aim of this description is to show the oAuth1 Authentication flow on basis of a python script. See also for the authentication flow the information on page Three Legged OAuth - ImmoScout24 API Developer Portal – The Real Estate APIs.

In preparation for this description you need the requests_oauthlib library for python. There might also be other libraries you can use, but here we are concentration on this one. For checking if it is already installed you can use the following command in your command prompt or terminal window:

pip show library_name

Replace “library_name” by the name of the library your are checking for. In this case replace it by requests_oauthlib. If it is not yet installed open a command command prompt or terminal window and use the following command:

pip install library_name

Or use

pip3 install library_name

if you use pip3.

This python script is for the sandbox. You also need to have a sandbox test account for the authentication process. The test account credentials have you gotten during the api keys creation process in the self-service portal. Here you can also create a new sand box test account and get new credentials.
To use it on production you have to remove the prefix “sandbox-” and use API credentials for the live system.
To keep it really simply the tokens are saved in a text file for later use for doing requests later on. Keep in mind to keep the token secure that misuse is impossible.

Here is the script:


from requests_oauthlib import OAuth1Session

# Define file path and open access token file
access_token_file = open("/Users/your_place/Desktop/Python_Test/OAUTH1_Requests/access_token_file.txt", "w")

# Set sandbox API credentials
client_key = "Your_APIKey"  # Sandbox
client_secret = "Your_API_Secret"  # Sandbox

# Write client key to access token file
access_token_file.write(client_key + "\n")

# Write client secret to access token file
access_token_file.write(client_secret + "\n")

# Define callback URI
callback_uri = "http://localhost"

# Request token URL
request_token_url = 'https://rest.sandbox-immobilienscout24.de/restapi/security/oauth/request_token'

# Initialize OAuth1Session
oauth = OAuth1Session(client_key, client_secret=client_secret, callback_uri=callback_uri)

# Fetch request token
fetch_response = oauth.fetch_request_token(request_token_url)
resource_owner_secret = fetch_response.get('oauth_token_secret')
resource_owner_key = fetch_response.get('oauth_token')

# Display tokens
print("token_secret:", resource_owner_secret)
print("token:", resource_owner_key)

# Display URL to fetch verifier
print("open the following URL, confirm your account and fetch the verifier form the url")
print("https://rest.sandbox-immobilienscout24.de/restapi/security/oauth/confirm_access?oauth_token=" + resource_owner_key + "&oauth_callback=" + callback_uri)

# Input verifier
verifier = input("Enter the Verifier here: ")

# Get access token URL
access_token_url = 'https://rest.sandbox-immobilienscout24.de/restapi/security/oauth/access_token'

# Fetch access token
oauth_session = OAuth1Session(client_key=client_key, client_secret=client_secret, resource_owner_key=resource_owner_key, resource_owner_secret=resource_owner_secret, verifier=verifier, callback_uri=callback_uri)
oauth_tokens = oauth_session.fetch_access_token(access_token_url)

# Get access token and token secret
resource_owner_key = oauth_tokens.get('oauth_token')
resource_owner_secret = oauth_tokens.get('oauth_token_secret')

# Write access token and token secret to access token file
access_token_file.write(resource_owner_key + "\n")
access_token_file.write(resource_owner_secret)

# Close access token file
access_token_file.close()

Click on the Url and the browser gets opened automatically. But if not, you have to copy the URL and past it in a browser. If you not already logged into your sandbox test account in that browser you will be invited to do so. After log in you will be informed that a application wants to connect to your account. You have to confirm this step.

Then you will get an error message if you use “localhost” as a return url like “Unable to connect” but that’s account. Just copy the verifier out of the browser url. It start with “oauth_verifier=blabla”. In that case “blabla” . Don’t copy the “&” and everything else that follows. You will be ask by the script to enter the verifier.

That’s it. Done.

Now you have everything for doing requests.

One more sentence on validity of the oAuth1 token. The token gets invalid by setting new account credentials or if the customer account was blocked. In such cases the authentication process need do be done again for receiving a new valid token.

We are interested in your feedback!

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: ext-heim0815 Irgendwas YES NOT_APPLICABLE YES.
Later we update this files, but only transfer the changed elements: ext-heim0815 Irgendwas DAZU YES.
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 place 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

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

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.

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.

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:

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

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.

Private use

Can I use your API's for private use i.e. searching for listings?

As of now, our APIs and related products are designed solely for commercial and enterprise use. Private use, including searching for listings, is not supported.