Customer Website
This tutorials 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 oAuto 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 using the Postman Collection, 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.
The following SDKs includes the authentication:
- PHP-SDK with immobilienscout24 support
- .Net-SDK without immobilienscout24 support
- Java implementation for oAuth with immobilienscout24 support
- Java-SDK with immobilienscout24 support
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.
5) You code the access token request with the verifier code as parameter.
Obtaining all real estate objects of an immobilienScout24 customer (export API)
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 un Germany:
1 | |
Request for 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.
1 | |
Request for 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.
1 | |
Request for a list of real estates:
1 | |
Request for a specific real estate:
1 | |