Tutorials, SDKs and Plugins

Customer-Website

This tutorial is for all API clients, which need to display the real estate objects of an immobilienscout24 customer on it's website.

Please register for the api in order to get a live api access. Choose "Kundenwebsite / Immobilienverwaltungssoftware" so that your key has the right permissions.

 

You have to choose which API you want to use (the registration contains the permission for both APIs):

1) Search and Expose API: Fits to realtors with more than 100 objects. There is no search request, which hands out all objects at once.

2) Import/Export API: Fits for smaller realtors. You get all objects handed out with one request. But no filtering, paging, sorting.

 

 


Here's an overview, which compares the APIs on feature level:

Feature Search and Expose API Import/Export API
search over all real estate types no. You can only search within one real estate type. If you need to perform a search over more than one real estate type at a time (for example "Wohnimmobilien, Kaufimmobilien, Gewerbeimmobilien", use the other API. all real estate objects are handed out with one request, but without search features like paging/sorting/search filtering
Sorting, Paging, Search filter Yes No. You have to build these features by yourself
PHP-SDK Search and Expose is included Export to IS24 is included

 


Authentification and Authorisation

  • we use oAuth 1.0a.
  • The autorisation must be done one-time-only: you'll get an access token, that you can save in your application, forever.
  • You can do this autorisation with our Playground, so that you don't need to code a client. See the tutorial, below.
  • the is24 user is identified by username, not by customer number
  • Every REST API request must be signed.
  • Read the oAuth tutorial for more details on oAuth.

 


SDKs which include the authentification

 

 

oAuth by our playground

You can get the autorisation of a is24 user (the access token) without having to code, by using our playground:

 

file

You can only do this together with your client on one computer. It doesn't work if you cannot urls from the playground to your client.

  1. enter your oauth key and secret in the playground in the upper left boxes, click on the right server (sandbox or live) and confirm by clicking "Change".
  2. click „Request Token“ bottom left
  3. click „Authorize Token“ and you're being redirected to our SingleSignOn page, where your client /the ImmobilienScout24 customer needs to login.
  4. After login, he gets a screen where he has to authorize your application and you're being redirected to the playground
  5. click "Access Token" and you'll get the acccess token and secret. Which will never expire and which you'll save in your database.

 

Implement oAuth in your application

use the oauth step-by-step-tutorial

You get the access token and access token secret by following these steps:

  1. Send a request token request with a callback to your server or entering "oob" instead of the callback url
  2. Send an authorize token request and open the authorize token url, this will open a browser window which calls the single-sign-on page in which the customer needs to login and after that, authorizes your application
  3. IS24 sends a request to the callback adress, which you've entered in step 1). By sending this callback request, you'll get the verifier.
  4. The verifier allows you to generate the access token and the access token secret. You save the access token and the access token secret in your database AND use it within every request. You don't need to save the verifier.

Coding: You code the access token request with the verifier code as parameter (you cannot do this in the playground, since you cannot enter/change the verifier.

 

Obtaining all real estate objects of an immobilienScout24 customer (export API)

  • It exists no search request to obtain all exposes of a customer.
  • The search results are handed out with paging. The page size can be set to max. 200 results (default = 15).


Search parameter:

  • realestate. Mandatory. You have to do a search request for every real estate type and collect the results on the client-side. List of real estate types
  • region: For obtaining objects from whole of germany, please use the geocode "1276". There's a webservice for obtaining geocodes.
  • channel: The publish channel. Our customers kann publish their exposes on www.immobilienscout24.de (channel=is24) and/or on their homepage (channel=hp). Please use channel=hp for this given usecase. Your API access normally doesn't allow access to channel=is24.
  • username: the is24 username of your customer. You can enter "me" instead. Both only work aftger your customer has authorized your application.

 

Request for all objects in Germany:

GET https://rest.immobilienscout24.de/restapi/api/search/v1.0/search/region?realestatetype={realestatetype}&geocodes={geocodes}&channel=hp&username=[username or "me"]

International objects

You cannot perform a world-wide search. Solution: One request for all continents, except for Europe and one request for all countries in Europe, except for Germany.

All Continents, except for Europe:

The body can be left empty.

GET https://rest.immobilienscout24.de/restapi/api/search/v1.0/search/region?realestatetype=ApartmentBuy&geocodes=1%2C2%2C3%2C4%2C5%2C6

Groups

A group is a conglomeration of customers. Groups are only created by Immobilienscout24. Customers need to publish their objects in a group first, so that you can obtain these exposes by using the search api with the group parameter. The search parameter is: channel=[groupid]. You can get the groupid from our support or from the account manager. There's more to groups in the FAQ. You only need 2-legged oauth for accessing groups.

Search request for groups:

GET https://rest.immobilienscout24.de/restapi/api/search/v1.0/search/region?realestatetype={realestatetype}&geocodes={geocodes}&channel=[börsen-id]

Obtaining all real estate objects of an immobilienScout24 customer (export API)

Hands out the list of real estates:

GET https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/{username}/realestate

With this request, you'll get the real estate object itself:

GET https://rest.immobilienscout24.de/restapi/api/offer/v1.0/user/{username}/realestate/{id} or .../ext-{externalId}