Valuation Plus API

This API hands out a brief valuation of a realestate object and additionally - if you have the permission - prices of comparable real estates.

All possible request parameters are very similar to the Plus valuation web flow. So please have a look there first to get an impression of what is the meaning of the request parameters: http://www.immobilienscout24.de/realestatevaluation/plus3/index.html.

POST https://rest.immobilienscout24.de/restapi/api/ibw/v2.0.1/valuation/plus

Supported media types

  • JSON (Accept: application/json)

Authorization requirements

  • At least a System Key is required for this operation. See Authentication via Two-legged OAuth for further details.
  • A special API permission (contact us: service@immobilienscout24.de)

Request

Path/query parameters

none


  • A JSON request object has to be send in the body of the post request which provides all available information of the real estate that should be valuated. It follows a list of all possible keys in the JSON request object.
  • All keys marked in bold are mandatory. Depending on the type of the real estate (key realEstateType) the key floor has to be set if it is an APARTMENT, otherwise (in case of a house) the key siteArea has to be set. This keys are marked with a i.
  • Furthermore, either a coordinate or an address has to be provided. In both cases all fields within that object have to be set and will not be accepted if any of them is empty or has a wrong format. That means that if you provide a address, you also have to provide the street, houseNo, zip and city.
  • Please note that the keywords are case sensitive, e.g. END_TERRACE_HOUSE will be recognized, but end_terrace_house not.

Keys in JSON request body:

Value Value details
comparisonRealEstates = true | false (default false) integer
rented
true, false
realEstateType APARTMENT, SINGLE_FAMILY_HOUSE, MID_TERRACE_HOUSE,  END_TERRACE_HOUSE, SEMIDETACHED_HOUSE
constructionYear Integer, minimal value "1500", max is the actual year e.g "2015"
roomCount ONE, ONE_HALF, TWO, TWO_HALF,THREE,  THREE_HALF, FOUR, FIVE, SIX_OR_MORE
livingArea Double
siteArea Double i
floor GROUND_FLOOR, FLOOR_1, FLOOR_2, FLOOR_3, FLOOR_4, FLOOR_5, FLOOR_6, BASEMENT i
penthouse true, false
lift true, false
balcony true, false
cellar true, false
garden true, false
coordinate (WGS84) i latitude Double
longitude
address i street

String

houseNo
zip
city
facilities: (the facilities always have to be provided in pairs of facility and quality)
wallCovering Facility GREAT, GOOD, AVERAGE, POOR
wallCoveringQuality Quality AS_NEW, WELL_KEPT, POOR
roof Facility GREAT, GOOD, AVERAGE, POOR
roofQuality Quality AS_NEW, WELL_KEPT, POOR
insulation Facility GREAT, GOOD, AVERAGE, POOR
insulationQuality Quality AS_NEW, WELL_KEPT, POOR
floorCovering Facility GREAT, GOOD, AVERAGE, POOR
floorCoveringQuality Quality AS_NEW, WELL_KEPT, POOR
window Facility GREAT, GOOD, AVERAGE, POOR
windowQuality Quality AS_NEW, WELL_KEPT, POOR
heating Facility GREAT, GOOD, AVERAGE, POOR
heatingQuality Quality AS_NEW, WELL_KEPT, POOR
sanitaryInstallation Facility GREAT, GOOD, AVERAGE, POOR

sanitaryInstallationQuality

Quality AS_NEW, WELL_KEPT, POOR
parking:

parkingSpace

Int [0..5]
basementGarage
singleGarage
duplex
carport
doubleGarage
exposure:

exposureView

VERY_ATTRACTIVE, ATTRACTIVE, TYPICAL, UNATTRACTIVE, VERY_UNATTRACTIVE
residentialEnvironment VERY_CALM, CALM, TYPICAL, NOISY, VERY_NOISY
amountOfSunlight VERY_BRIGHT, BRIGHT, AVERAGE, DARK, VERY_DARK
roomLayout VERY_SPACIOUS, SPACIOUS, AVERAGE, POOR, VERY_POOR

specialFeatures: (the special features always have to be given in pairs of cost and year)

Value Value details

builtInKitchenCost

integer
builtInKitchenYear integer
chimneyCost integer

chimneyYear

integer
landscapeGardeningCost integer
landscapeGardeningYear integer
solarCollectorCost integer
solarCollectorYear integer
summerhouseCost integer
summerhouseYear integer
swimmingpoolCost integer
swimmingpoolYear integer
wintergardenCost integer
wintergardenYear integer

returnPdf = true | false (default false)

pdfDisplayParameter

  • realtorLogoUrl :: String
  • realtorLogoAsBase64 :: String (... or inline as base64 encoded)
  • addressVisible :: true | false (default true)
  • demographicDataVisible :: true | false (default true)
  • exemplificationsVisible :: true | false (default true)
  • comparisonObjectsVisible :: true | false (default true)

Sample request

{
    "realEstateType":"MID_TERRACE_HOUSE",
    "constructionYear":1988,
    "livingArea":70.6,
    "siteArea":79.6,
    "roomCount":"THREE",
    "penthouse":"false",
    "rented":false,
    "lift":"false",
    "balcony":"false",
    "cellar":"false",
    "garden":"false",
    "address":{
        "street":"Andreasstraße",
        "houseNo":"10a",
        "zip":"10243",
        "city":"Berlin"
    },
    "facilities":{
        "wallCovering":"GREAT",
        "wallCoveringQuality":"WELL_KEPT",
        "roof":"GOOD", "roofQuality":"POOR",
        "insulation":"GOOD", "insulationQuality":"POOR",
        "floorCovering":"GOOD", "floorCoveringQuality":"POOR",
        "window":"GOOD", "windowQuality":"POOR",
        "heating":"AVERAGE", "heatingQuality":"POOR",
        "sanitaryInstallation":"GOOD", "sanitaryInstallationQuality":"AS_NEW"
    },
    "parking":{
        "parkingSpace":1,
        "basementGarage":2,
        "singleGarage":0
    },
    "exposures":{"amountOfSunlight":"VERY_BRIGHT"},
    "specialFeatures":{
        "builtInKitchenCost":1000, "builtInKitchenYear":1990,
        "chimneyCost":2400, "chimneyYear":2004,
        "solarCollectorCost":5400, "solarCollectorYear":2014
    }
}

Response

Status 201 RESSOURCE CREATED

Keys in response body:

Value Value details
variance double
priceTotal Integer
pricePerSqM Double
totalPriceVarianceHigh Integer
totalPriceVarianceLow Integer
comparisonRealEstates (will only be shown if requested and if consumer has the permission):  
obid Double
absoluteOriginalPrice Double
absoluteAdjustedPrice Double
originalPricePerSqm Double
adjustedPricePerSqm Double
offeringDate String
constructionYear Integer
ozid Integer
city String
street String
zip String
neighbourhoodId String
livingArea Double
siteArea Double
balconyOrGarden Boolean
rented Boolean

pdfContentBase64 :: String

Sample response without comparison real estates

{
    "priceTotal":200032,
    "pricePerSqM":2833.31,
    "variance":0.22,
    "totalPriceVarianceHigh":244039,
    "totalPriceVarianceLow":156025
}

STATUS 204 NO CONTENT

It is possible that the valuation of the given object does not return a result. In this case the HTTP status code 204 (No Content) is returned.

STATUS 400 BAD REQUEST

It is furthermore possible that the geocoding was not possible for the given address or coordinate and therefore no or no unique neighbourhoodId could be determined. In this case the HTTP status code is 400 (Bad Request) with a detailed error message in the body. If you don't want to receive a 400 there is the possibility to get a 204 (No Content) if the flag showGeocodingErrors is set to false.