OpenEstate-IS24-REST 0.6

OpenEstate-IS24-REST is a client library for the REST-Webservice of ImmobilienScout24.de written in Java. This library is used within OpenEstate-ImmoTool and in some of our clients projects in order to import / export their real estates to ImmobilienScout24.de.

Features

• authentication through OAuth
• read and write XML according to the specifications of the Webservice
• low level functions to call Import/Export API and Geo Information Service API
• high level functions for the export of multiple real estates (including contacts, attachments and streaming videos)
• create real estates randomly
• example web application for the OAuth verification process

Components

The library is split into different components:

• OpenEstate-IS24-REST-Core

  • Java classes, that represent the XML schemas of the Webservice
  • XML reading and writing according to the XML schemas of the Webservice
  • low level methods to access the Webservice (see ImportExport.java and GIS.java)
  • high level methods for a straightforward export of real estates (see ExportPool.java and ExportHandler.java)
  • communicate with the Webservice through java.net.HttpURLConnection (see DefaultClient.java)

• OpenEstate-IS24-REST-HC4

  • communicate with the Webservice through Apache HttpClient 4.5 (see HttpComponents4Client.java)

• OpenEstate-IS24-REST-Examples

  • some example classes to illustrate library usage

• OpenEstate-IS24-REST-WebApp

  • an example web application to illustrate the OAuth verification process (see VerificationServlet.java)

How to use

Download the latest release from GitHub. The provided archive contains all required files (compiled libraries, dependencies, source code and documentations).

Alternatively you can integrate the library from Maven Central Repository into your Maven project. Just add one or more of the following dependencies to your projects pom.xml (according to your requirements):

<dependency>
  <groupId>org.openestate.is24</groupId>
  <artifactId>OpenEstate-IS24-REST-Core</artifactId>
  <version>0.6</version>
</dependency>

<dependency>
  <groupId>org.openestate.is24</groupId>
  <artifactId>OpenEstate-IS24-REST-HC4</artifactId>
  <version>0.6</version>
</dependency>

You can find further information in the project wiki or in the docs subfolder.

Requirements

• You need to register for API access.
• You need to accept the terms of use.
• After the registration process you should receive a consumer token and consumer secret.

Dependencies

• Java 8 or newer
• commons-codec 1.15
• commons-io 2.11.0
• commons-lang 3.12.0
• commons-text 1.9
• Eclipse Implementation of JAXB 2.3.5
• Jakarta Activation 1.2.2
• Jakarta Annotations 1.3.5
• Jakarta XML Binding 2.3.3
• jaxb2-basics-runtime 0.12.0
• oauth-signpost 2.1.1
• SLF4J 1.7.30
• Lorem 2.1 (only required by RandomRealEstateFactory.java)
• Apache HttpClient 4.5 (optional) with further dependencies:
  • commons-logging 1.2
  • Apache HttpCore 4.4

Notes about JDK versions below 11

JAXB is bundled with JDK 8, was disabled / deprecated in JDK 9 & 10 and finally removed in JDK 11. Therefore, we're providing JAXB as an explicit dependency. See also "JAXB on Java 9, 10, 11 and beyond".

It is recommended to use this library with JDK 11 as it should work out of the box. In case you're using JDK 8, you might need to follow one of these steps documented at "JAXB Release Documentation":

JavaSE comes with JAXB 2.x API/implementation in rt.jar. Each version of JavaSE (6, 7, 8, ...) contains different version of JAXB 2.x API. Therefore, if you want to use different version of JAXB API/implementation than the one present in your version of JDK, you are required to override a portion of rt.jar with the new API. There are several ways to achieve this:

1. Place the jakarta.xml.bind-api-X.Y.Z.jar into $JRE_HOME/lib/endorsed. Do not put other JAXB jars into the endorsed directory. This essentially makes your JRE to "JRE X + JAXB 2.y". This would affect any other applications that use this JRE, and it's easy. On the other hand, in various scenarios you may not be able to alter the JRE.

2. Use the system property java.endorsed.dirs when you launch your application, and have it point to the directory which contains the jakarta.xml.bind-api-X.Y.Z.jar only. The directory must not contain any other jaxb artifacts. This allows you to use different version of JAXB for different applications.

See the endorsed directory mechanism for more details.

All provided dependencies should work with JDK 8. If compatibility problems occur, you might replace them with an earlier version.

Limitations

The use of the Webservice may be limited by ImmobilienScout24 to a maximal number of operations per day. Contact [email protected] if the limit is too low for your use case.

XML schemas

XML specifications for the different webservices are available at:

• Import/Export API

  • XML-Schemas for the production system
  • XML-Schemas for the sandbox system

• Geo Information Service API

  • XML-Schemas for the production system
  • XML-Schemas for the sandbox system

Changelog

Take a look at CHANGELOG.md for the full changelog.

License

This library is licensed under the terms of Apache License, Version 2.0. Take a look at LICENSE.txt for the license text.

Todo

• further testing
• implement other API's - e.g.
  • Expose API
  • Search API
  • Product Valuation Services API
  • Construction Financing API

Further information

• OpenEstate-IS24-REST at GitHub
• Releases of OpenEstate-IS24-REST
• Changelog of OpenEstate-IS24-REST
• API documentation of OpenEstate-IS24-REST
• ImmobilienScout24 Developer Center
• ImmobilienScout24-REST-API Forum
• ImmobilienScout24-REST-API Playground
• API registration for the production system
• API registration for the sandbox system
• alternative Java SDK by ImmobilienScout24