POST Real Estate

This method creates a real estate object.

This method creates a real estate object ("Immobilie").
The new object is deactivated by default. Please use the webservice Publish for publishing the real estate.

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

  • Don't encode the xml/json if you send it within the body. It won't work (error code 409)
  • "Preis auf Anfrage" is set by entering a "0" in the price field. This is only supported for "Grundstücke" (plots) and all "Gewerbeimmtypen" (commercial real estate types).
  • The tag "contact" is optional. If you don't enter a contact id, we'll take the standard contact address of the realtor.
  • if the address cannot be geocoded by IS24 then you should send the "wgs84Coordinate" (vice versa: should be omitted for geocodable addresses)
  • externalID is optional. If it is not entered, than we'll set the scout object id automatically as externalId.
  • If you use an existing foreignobjectid, you'll get a 409 error message (the foreignobjectid needs to be unique within the real estate objects of a realtor/customer).
  • If you want to change an existing real estate objects, use PUT.
  • Alternatively: you can send a GET REALESTATE without the foreignobjectid and you'll get an object list with lastmodifcationdate. Therewith, you can decide, which real estate object must be send per POST/PUT 
  • realEstateProjectId can't be set by the realestate api! Use the RealEstateProject Ressource to add the realEstates to your project.
  • lastModificationDate is ignored
  • the attribute "marketingType" in the price element and additionalCosts element is optional. Default is rent. If you want to POST an object with marketingType = "buy", then you must change the commercialisationType to "BUY".
  • External id which contains "/" needs to be url encoded
  • "<" and ">" are not allowed

 

Free text fields: html and CDATA are not supported!!! For line breaks please use

  • for xml: &#xD;
  • for json: \n

Supported media types

  • XML (Accept: application/xml)
  • JSON (Accept: application/json)

Authorization requirements

A System Key and an authenticated user are required for this operation:

Please use a secure connection (https) for this operation.

Java Code Example

String body = …//Das XML, welches das Realestat beschreibt
 URL url = …//URL für den POST request
  connection = (HttpURLConnection) url.openConnection();

  connection.setRequestMethod("POST");
  connection.setRequestProperty("Content-Type", "application/xml; charset=utf-8");
  connection.setRequestProperty("Content-Length", "" + Integer.toString(body.getBytes().length));
  connection.setRequestProperty("Content-Language", "en-US");
  connection.setRequestProperty("Accept", "application/xml");

  connection.setUseCaches(false);
  connection.setDoInput(true);
  connection.setDoOutput(true);

  signRequest(connection);
  // Send request
  DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
  wr.writeBytes(body);
  wr.flush();
  wr.close();

  connection.connect();

  String response = getResponse(connection.getInputStream());
                                               
//parse the respone if you need the data

  return response;

International real estates

Real estates abroad are handled the same way as german-located real estates, except for the address element:

  • You need to deliver the country code (ISO-Code) and region name (string) from the region list
  •     Country: We use the official ISO-Codes for countries, which you can find here
  •     Region: names can be accessed by the geohierarchy api, which is described in this tutorial
  • Camelcase is relevant, so you have to post it 1:1 as defined in the list.
  • City is required
  • street, house number and zip code are optional but highly recommended input regarding the geocoding success
  • The <wgs84Coordinate> element is optional. If you do not deliver this <wgs84Coordinate> element, IS24 tries to geocode the given address. If this geocoding is successful, the resulting coordinates are added to the real estate object. Otherwise it is stored with the given address and the given country and region only
  • We currently only support the following real estate types: apartment buy (Wohnung Kauf), house buy (Haus Kauf), living buy site (Grundstück Kauf) and trade site (Grundstück Gewerbe)
...
<address>
    <street>Kalverstraat</street>
    <houseNumber>1</houseNumber>
    <postcode>5912 HG</postcode>
    <city>Amsterdam</city>
    <internationalCountryRegion>
        <country>NLD</country>
        <region>Nord-Holland</region>
    </internationalCountryRegion>
    <wgs84Coordinate>
        <latitude>52.51245</latitude>
        <longitude>13.43134</longitude>
    </wgs84Coordinate>
</address>
...

Request

Path Parameters

  • Username: the username which the user uses for logging in to www.immobilienscout24.

  • Username: "me" can be used instead of the username, when the user is logged in by 3-legged oauth.

Query Parameters

  • usenewenergysourceenev2014values=true - New param since 20.08.2014. Due to downward compatibility you can POST the new energySourceEnev2014 values only by using that query param: BIO_ENERGY, WIND_ENERGY, HYDRO_ENERGY, ENVIRONMENTAL_THERMAL_ENERGY,COMBINED_HEAT_AND_POWER_FOSSIL_FUELS,
    COMBINED_HEAT_AND_POWER_RENEWABLE_ENERGY, COMBINED_HEAT_AND_POWER_REGENERATIVE_ENERGY, COMBINED_HEAT_AND_POWER_BIO_ENERGY

Body

XML

  • if a contact id is entered, it has to belong to the offerer of the real estate object.
<?xml version="1.0" ?>
<realestates:apartmentBuy xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:ns2="http://rest.immobilienscout24.de/schema/platform/gis/1.0" xmlns:realestates="http://rest.immobilienscout24.de/schema/offer/realestates/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
    <externalId>extID</externalId>
    <title>RestAPi appartmentBuy</title>
    <address>
        <street>Andreasstraße</street>
        <houseNumber>10</houseNumber>
        <postcode>10243</postcode>
        <city>Berlin</city>
        <wgs84Coordinate>
            <latitude>52.51245</latitude>
            <longitude>13.43134</longitude>
        </wgs84Coordinate>
    </address>
    <apiSearchData>
        <searchField1>apiSearchField1</searchField1>
        <searchField2>apiSearchField2</searchField2>
        <searchField3>apiSearchField3</searchField3>
    </apiSearchData>
    <descriptionNote>Objektbeschreibung(noch 2000 Zeichen) description-note 
 after line break this text is in the next row</descriptionNote>
    <furnishingNote>Ausstattung(noch 2000 Zeichen)</furnishingNote>
    <locationNote>Lage(noch 2000 Zeichen)</locationNote>
    <otherNote>Sonstiges(noch 2000 Zeichen)</otherNote>
    <showAddress>true</showAddress>
    <contact id="53323004"/>
    <apartmentType>MAISONETTE</apartmentType>
    <floor>2</floor>
    <lift>true</lift>
    <energyCertificate>
        <energyCertificateAvailability>AVAILABLE</energyCertificateAvailability>
        <energyCertificateCreationDate>BEFORE_01_MAY_2014</energyCertificateCreationDate>
    </energyCertificate>
    <cellar>YES</cellar>
    <handicappedAccessible>YES</handicappedAccessible>
    <numberOfParkingSpaces>1</numberOfParkingSpaces>
    <condition>WELL_KEPT</condition>
    <lastRefurbishment>2010</lastRefurbishment>
    <interiorQuality>SOPHISTICATED</interiorQuality>
    <constructionYear>1995</constructionYear>
    <freeFrom>sofort</freeFrom>
    <heatingTypeEnev2014>FLOOR_HEATING</heatingTypeEnev2014>
    <energySourcesEnev2014>
        <energySourceEnev2014>WOOD_CHIPS</energySourceEnev2014>
        <energySourceEnev2014>LIQUID_GAS</energySourceEnev2014>
        <energySourceEnev2014>COAL_COKE</energySourceEnev2014>
        <energySourceEnev2014>COAL</energySourceEnev2014>
        <energySourceEnev2014>HEAT_SUPPLY</energySourceEnev2014>
        <energySourceEnev2014>COMBINED_HEAT_AND_POWER_RENEWABLE_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>DISTRICT_HEATING</energySourceEnev2014>
        <energySourceEnev2014>ENVIRONMENTAL_THERMAL_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>WOOD</energySourceEnev2014>
        <energySourceEnev2014>SOUR_GAS</energySourceEnev2014>
        <energySourceEnev2014>STEAM_DISTRICT_HEATING</energySourceEnev2014>
        <energySourceEnev2014>WIND_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>ACID_GAS</energySourceEnev2014>
        <energySourceEnev2014>BIO_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>LOCAL_HEATING</energySourceEnev2014>
        <energySourceEnev2014>SOLAR_HEATING</energySourceEnev2014>
        <energySourceEnev2014>COMBINED_HEAT_AND_POWER_REGENERATIVE_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>GEOTHERMAL</energySourceEnev2014>
        <energySourceEnev2014>HYDRO_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>GAS</energySourceEnev2014>
        <energySourceEnev2014>COMBINED_HEAT_AND_POWER_FOSSIL_FUELS</energySourceEnev2014>
        <energySourceEnev2014>OIL</energySourceEnev2014>
        <energySourceEnev2014>PELLET_HEATING</energySourceEnev2014>
        <energySourceEnev2014>COMBINED_HEAT_AND_POWER_BIO_ENERGY</energySourceEnev2014>
        <energySourceEnev2014>ELECTRICITY</energySourceEnev2014>
    </energySourcesEnev2014>
    <buildingEnergyRatingType>ENERGY_CONSUMPTION</buildingEnergyRatingType>
    <thermalCharacteristic>123.85</thermalCharacteristic>
    <energyConsumptionContainsWarmWater>YES</energyConsumptionContainsWarmWater>
    <numberOfFloors>5</numberOfFloors>
    <usableFloorSpace>70.00</usableFloorSpace>
    <numberOfBedRooms>1</numberOfBedRooms>
    <numberOfBathRooms>2</numberOfBathRooms>
    <guestToilet>YES</guestToilet>
    <parkingSpaceType>UNDERGROUND_GARAGE</parkingSpaceType>
    <rented>YES</rented>
    <rentalIncome>895.00</rentalIncome>
    <listed>YES</listed>
    <parkingSpacePrice>15000.00</parkingSpacePrice>
    <summerResidencePractical>YES</summerResidencePractical>
    <price>
        <value>175000.00</value>
        <currency>EUR</currency>
        <marketingType>PURCHASE</marketingType>
        <priceIntervalType>ONE_TIME_CHARGE</priceIntervalType>
    </price>
    <livingSpace>75.00</livingSpace>
    <numberOfRooms>3</numberOfRooms>
    <energyPerformanceCertificate>true</energyPerformanceCertificate>
    <builtInKitchen>true</builtInKitchen>
    <balcony>true</balcony>
    <certificateOfEligibilityNeeded>false</certificateOfEligibilityNeeded>
    <garden>true</garden>
    <courtage>
        <hasCourtage>YES</hasCourtage>
        <courtage>Provisionshöhe (brutto)</courtage>
        <courtageNote>Provisionshinweis (noch 500 Zeichen)</courtageNote>
    </courtage>
    <serviceCharge>575</serviceCharge>
</realestates:apartmentBuy>

JSON

  • if a contact id is entered, it has to belong to the offerer of the real estate object.
    {
       "realestates.apartmentBuy":
       {

           "externalId": "extID1",
           "title": "RestAPi appartmentBuy",
           "creationDate": "2014-08-12T15:56:52.000+02:00",
           "address":
           {
               "street": "Andreasstraße",
               "houseNumber": "10",
               "postcode": "10243",
               "city": "Berlin",
               "wgs84Coordinate":
               {
                   "latitude": 52.51245,
                   "longitude": 13.43134
               },
           },
           "apiSearchData":
           {
               "searchField1": "apiSearchField1",
               "searchField2": "apiSearchField2",
               "searchField3": "apiSearchField3"
           },
           "realEstateState": "INACTIVE",
           "descriptionNote": "Objektbeschreibung(noch 2000 Zeichen) description-note \n after line break this text is in the next row",
           "furnishingNote": "Ausstattung(noch 2000 Zeichen)",
           "locationNote": "Lage(noch 2000 Zeichen)",
           "otherNote": "Sonstiges(noch 2000 Zeichen)",

           "showAddress": "true",
           "contact":
           {
               "@id": "53323004"
           },
           "apartmentType": "MAISONETTE",
           "floor": 2,
           "lift": "true",
           "energyCertificate":
           {
               "energyCertificateAvailability": "AVAILABLE",
               "energyCertificateCreationDate": "BEFORE_01_MAY_2014"
           },
           "cellar": "YES",
           "handicappedAccessible": "YES",
           "numberOfParkingSpaces": 1,
           "condition": "WELL_KEPT",
           "lastRefurbishment": 2010,
           "interiorQuality": "SOPHISTICATED",
           "constructionYear": 1995,
           "freeFrom": "sofort",
           "heatingTypeEnev2014": "FLOOR_HEATING",
           "energySourcesEnev2014":
           {
               "energySourceEnev2014":
               [
                "WOOD_CHIPS",
               "LIQUID_GAS",
               "COAL_COKE",
               "COAL",
               "HEAT_SUPPLY",
               "COMBINED_HEAT_AND_POWER_RENEWABLE_ENERGY",
               "DISTRICT_HEATING",
               "ENVIRONMENTAL_THERMAL_ENERGY",
               "WOOD",
               "SOUR_GAS",
               "STEAM_DISTRICT_HEATING",
               "WIND_ENERGY",
               "ACID_GAS",
               "BIO_ENERGY",
               "LOCAL_HEATING",
               "SOLAR_HEATING",
               "COMBINED_HEAT_AND_POWER_REGENERATIVE_ENERGY",
               "GEOTHERMAL",
               "HYDRO_ENERGY",
               "GAS",
               "COMBINED_HEAT_AND_POWER_FOSSIL_FUELS",
               "OIL",
               "PELLET_HEATING",
               "COMBINED_HEAT_AND_POWER_BIO_ENERGY",
               "ELECTRICITY"
               ]
           },
           "buildingEnergyRatingType": "ENERGY_CONSUMPTION",
           "thermalCharacteristic": 123.85,
           "energyConsumptionContainsWarmWater": "YES",
           "numberOfFloors": 5,
           "usableFloorSpace": 70,
           "numberOfBedRooms": 1,
           "numberOfBathRooms": 2,
           "guestToilet": "YES",
           "parkingSpaceType": "UNDERGROUND_GARAGE",
           "rented": "YES",
           "rentalIncome": 895,
           "listed": "YES",
           "parkingSpacePrice": 15000,
           "summerResidencePractical": "YES",
           "price":
           {
               "value": 175000,
               "currency": "EUR",
               "marketingType": "PURCHASE",
               "priceIntervalType": "ONE_TIME_CHARGE"
           },
           "livingSpace": 75,
           "numberOfRooms": 3,
           "energyPerformanceCertificate": "true",
           "builtInKitchen": "true",
           "balcony": "true",
           "certificateOfEligibilityNeeded": "false",
           "garden": "true",
           "courtage":
           {
               "hasCourtage": "YES",
               "courtage": "Provisionshöhe (brutto)",
               "courtageNote": "Provisionshinweis (noch 500 Zeichen)"
           },
           "serviceCharge": 575
       }
    }

Response

The following section includes the HTTP status code, a short description and examples for the response body content of a successful processed request.
Error responses as well as other simple message responses are described in detail within the common message responses.

  • Status 201 Created: This status code is returned after a new entity of a resource was successfully created.

Header

Location: Link to the newly created resource.

Body

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0"
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <message>
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
        <message>Resource [REALESTATE] with id [123456] has been created.</message>
        <id>123456</id>
    </message>
</common:messages>

JSON


{
  "common.messages":[
    {
      "message":{
        "messageCode":"MESSAGE_RESOURCE_CREATED",
        "message":"Resource [REALESTATE] with id [123456] has been created."
        "id":62558084
      }
    }
  ]
}