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 at least city (string) and from the region list the country code (ISO-Code) and region name (string).
  •     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.
  • street, house number and zip code are optional
  • wgs 84 coordinates are ignored, since we do not geocode international real estates
  • We only support the following real estate types: appartment buy (Wohnung Kauf), house buy (Haus Kauf), living buy site (Grundstück Kauf) and tradeSite (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>
</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
      }
    }
  ]
}