Immobilienscout 24 API

We implemented an interface to immobilienscout24.de (is24 hereafter). When we found that there was no SDK available for Node.js, we built one ourself. It’s not released and a little coupled to our use case. Though if there is enough demand and polishing, releasing it should be possible.

Following there a a couple of caveats we found and how to avoid them.

JSON Validation

Updating a contact fails depending on the payload’s properties’ order. As you can see in this example below. In the example below we first create a contact and then add a phone number to it. The first try works the second does not. The only difference is where the property `title` is.

Takeaway:

• Use the order found in the examples (see the JSON example here).
• Pray that you don’t use a JavaScript environment in which the properties of an object are not ordered (they don’t have to be, according to the ECMA standard).

This could happen for any other resource type as well, though this is the only case we found where this happened.

Schemas

These tables are really useful: http://api.immobilienscout24.de/our-apis/import-export/ftp-vs-api/.

Sadly they only exit for the REALESTATE resource types. If you want to know all the properties of any type the API supports check the restapi-java-sdk on GitHub.

The examples in the documentation are good, but not exhaustive since

• they don’t contain all optional fields,
• it’s not apparent which fields are required and which are optional,
• in case of enumerations it’s not apparent what values are possible.

It would be awesome to have the other resource types documented exactly as the REALESTATE ones.

Request Signing

All requests to is24 have to be signed with the OAuth tokens and secrets.

This wasn’t straightforward for us, never having seen that. After some trial and error (kudos to nouncer.com for this helpful tool) using oauth-signature.js is what worked for us:

When struggling

Make sure to have look at the error code page and check out the playground (like an apigee console) for oauth token/secret creation and trying out stuff.