Skip to content

Valuation

POST valuation/property_value

Performs valuations for the specified real estate properties on the specified valuation dates. The endpoint can be used to do a valuation of a single property, to create time series or to perform bulk valuations.

The number of valuations per call may not exceed 50, i.e. you can perform valuations for 1 property on 50 dates or for 50 properties on 1 date, but not for 50 properties on 50 dates.

Requests#

Example Request (Simple)#

curl -X POST 'https://api.pricehubble.com/api/v1/valuation/property_value' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
  -d '{
  "dealType": "sale",
  "valuationInputs": [
    {
      "property": {
        "location": {
          "address": {
            "postCode": "8037",
            "city": "Zurich",
            "street": "Nordstrasse",
            "houseNumber": "391"
          }
        },
        "propertyType": {
          "code": "apartment"
        },
        "buildingYear": 1990,
        "livingArea": 100
      }
    }
  ],
  "dossierId": "3bac39b8-2d84-4ae9-a693-40502071ea5d",
  "countryCode": "CH"
}'

Example Request (Multi-Family House)#

curl -X POST 'https://api.pricehubble.com/api/v1/valuation/property_value' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
  -d '{
  "dealType": "sale",
  "valuationInputs": [
    {
      "property": {
        "location": {
          "coordinates": {
            "latitude": 53.56818,
            "longitude": 10.037133
          }
        },
        "propertyType": {
          "code": "multi_family_house"
        },
        "buildingYear": 1850,
        "livingArea": 1500.00,
        "landArea": 1000.00,
        "numberOfUnits": 15,
        "annualRentIncome": 1000000
      }
    }
  ],
  "dossierId": "3bac39b8-2d84-4ae9-a693-40502071ea5d",
  "countryCode": "DE"
}'

Example Request (Advanced)#

curl -X POST 'https://api.pricehubble.com/api/v1/valuation/property_value' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
  -d '{
  "dealType": "sale",
  "valuationDates": [
    "2018-10-01",
    "2019-01-01"
  ],
  "valuationInputs": [
    {
      "property": {
        "location": {
          "coordinates": {
            "latitude": 47.3968601,
            "longitude": 8.5153549
          }
        },
        "propertyType": {
          "code": "apartment",
          "subcode": "apartment_normal"
        },
        "buildingYear": 1990,
        "numberOfRooms": 3.5,
        "numberOfBathrooms": 1,
        "balconyArea": 6.00,
        "gardenArea": 10.00,
        "livingArea": 100.00,
        "numberOfIndoorParkingSpaces": 1,
        "numberOfOutdoorParkingSpaces": 2,
        "floorNumber": 2,
        "hasLift": false,
        "energyLabel": "minergie",
        "quality": {
          "bathrooms": "simple",
          "kitchen": "normal",
          "flooring": "high_quality",
          "windows": "luxury"
        },
        "condition": {
          "bathrooms": "renovation_needed",
          "kitchen": "renovation_needed",
          "flooring": "well_maintained",
          "windows": "new_or_recently_renovated"
        }
      }
    }
  ],
  "returnScores": true,
  "dossierId": "3bac39b8-2d84-4ae9-a693-40502071ea5d",
  "countryCode": "CH"
}'

Valuation Request Fields Description#

Field Description Type Remarks
dealType Deal type of the valuation string Valid values are sale or rent. rent is not accepted for multi_family_house property type code.
valuationDates List of dates for each property to be valuated against array of dates default: [<current date>], min items: 1, max items: 50, date format: "YYYY-MM-DD"
valuationInputs array min items: 1, max items: 50
valuationInputs[i].property Property description Property A mixed array of multi_family_houses and apartments / houses is not supported
valuationInputs[i].valuationDates List of dates for current property to be valuated against array of dates Overrides the global valuationDates
default: [<current date>], min items: 1, max items: 50, date format: "YYYY-MM-DD"
returnScores Whether to return scores in the response boolean default: true
Scores are currently only supported for CH country code.
Valuations without scores might perform faster.
dossierId ID of the dossier string If this field is added to the request, then the location must be the same as the dossier's location (address or coordinates)
countryCode ISO country code string In France, sale valuations are supported for the following remote territories: Guadeloupe, Guyane, Martinique and Réunion; any other remote territories and rent valuations are currently not supported.

Response#

Example Response (Simple)#

{
  "valuations": [
    [
      {
        "salePrice": 374000,
        "salePriceRange": {
          "lower": 329000,
          "upper": 418000
        },
        "confidence": "medium",
        "currency": "CHF",
        "coordinates": {
          "latitude": 47.3968677,
          "longitude": 8.515364
        }
      }
    ]
  ]
}

Example Response (Multi-Family House):#

{
  "valuations": [
    [
      {
        "confidence": "medium",
        "coordinates": {
          "latitude": 53.56818,
          "longitude": 10.037133
        },
        "currency": "EUR",
        "salePrice": 5702800,
        "salePriceRange": {
          "lower": 4790300,
          "upper": 6615200
        }
      }
    ]
  ]
}

Example Response (Advanced)#

{
  "valuations": [
    [
      {
        "salePrice": 374000,
        "salePriceRange": {
          "lower": 329000,
          "upper": 418000
        },
        "confidence": "medium",
        "coordinates": {
          "latitude": 47.3968601,
          "longitude": 8.5153549
        },
        "currency": "CHF",
        "scores": {
          "location": 0.551
        }
      },
      {
        "salePrice": 374000,
        "salePriceRange": {
          "lower": 329000,
          "upper": 418000
        },
        "confidence": "medium",
        "currency": "CHF",
        "scores": {
          "location": 0.551
        }
      }
    ]
  ]
}

Example Error Response 1 ("Local" error)#

HTTP Status Code: 200

{
  "valuations": [
    [
      {
        "salePrice": 374000,
        "salePriceRange": {
          "lower": 329000,
          "upper": 418000
        },
        "confidence": "medium",
        "coordinates": {
          "latitude": 47.3968601,
          "longitude": 8.5153549
        },
        "currency": "CHF",
        "scores": {
          "location": 0.551
        }
      },
      {
        "status": {
          "code": 400,
          "message": "numberOfRooms: Must be between 1 and 12."
        }
      }
    ]
  ]
}

Example Error Response 2 ("Global" error)#

HTTP Status Code: 400

{
  "message": "'1990' is not of type 'integer'"
}
Field Description Type Remarks
valuations List of valuations per each property per each date array of arrays of Valuations valuations[i][j] contains the valuation for property i on date j

Valuation#

Field Description Type Remarks
currency Currency of the valuation Currency
coordinates Coordinates resolved from the address specified in the request (or coordinates from the request if they have been provided) Coordinates
salePrice Estimated sale price value of the property integer Only present if dealType is sale
salePriceRange.lower Estimated lower bound of the property's sale price value integer Only present if dealType is sale
salePriceRange.upper Estimated upper bound of the property's sale price value integer Only present if dealType is sale
rentGross Estimated monthly gross rent value of the property integer Only present if dealType is rent. Currently not available in JP
rentGrossRange.lower Estimated lower bound of the property's gross rent value integer Only present if dealType is rent. Currently not available in JP
rentGrossRange.upper Estimated upper bound of the property's gross rent value integer Only present if dealType is rent. Currently not available in JP
rentNet Estimated monthly net rent value of the property integer Only present if dealType is rent. Currently not available in AT
rentNetRange.lower Estimated lower bound of the property's net rent value integer Only present if dealType is rent. Currently not available in AT
rentNetRange.upper Estimated upper bound of the property's net rent value integer Only present if dealType is rent. Currently not available in AT
value Estimated market value of the property integer Deprecated since 2019-05-20. Replaced by salePrice (if dealType is sale) and rentGross (if dealType is rent)
valueRange.lower Estimated lower bound of the property's market value integer Deprecated since 2019-05-20. Replaced by salePriceRange.lower (if dealType is sale) and rentGrossRange.lower (if dealType is rent)
valueRange.upper Estimated upper bound of the property's market value integer Deprecated since 2019-05-20. Replaced by salePriceRange.upper (if dealType is sale) and rentGrossRange.upper (if dealType is rent)
confidence Confidence of the valuation string Valid values are poor, medium or good
scores.location Location score Score Currently only available in CH
status Failure status of the valuation object If the valuation for a specific property/date combination could not be performed, a "local" status object might be returned. The overall HTTP response status code can still be 200 in this case. The motivation for this behaviour is to avoid making the whole request fail if only 1 out of 50 property is invalid (bulk valuation case).
If you perform a valuation of a single property on a single date (single valuation case), errors will always be reported "globally", i.e. the HTTP response status code will reflect the error.
status.code The error code integer The error codes in the status object are inspired by HTTP status codes. The only code returned by the current implementation is:
  • 400: Bad request - The given property/date combination seems not to be valid
Additional codes could be returned in the future.
status.message Details about the error string

Below some more typical usage examples. d1, d2 and d3 are dates of the format YYYY-MM-DD. p1 and p2 are Properties. p1today, p2today, p1d1, p1d2, p2d3 are Valuations. The mandatory parameters dealType and countryCode have been omitted for the sake of brevity.

Valuation of a single property on the current date#

Request#

{
  "valuationInputs": [
    {
      "property": p1
    }
  ]
}

Response#

{
  "valuations": [
    [p1today]
  ]
}

Valuation of a single property on multiple dates (time series)#

Request#

{
  "valuationDates": [d1, d2],
  "valuationInputs": [
    {
      "property": p1
    }
  ]
}

Response#

{
  "valuations": [
    [p1d1, p1d2]
  ]
}

Valuation of multiple properties on the current date#

Request#

{
  "valuationInputs": [
    {
      "property": p1
    },
    {
      "property": p2
    }

  ]
}

Response#

{
  "valuations": [
    [p1today],
    [p2today]
  ]
}

Valuation of multiple properties on multiple distinct dates#

Request#

{
  "valuationDates": [d1],
  "valuationInputs": [
    {
      "property": p1
    },
    {
      "property": p2,
      "valuationDates": [d2, d3]
    }
  ]
}

Response#

{
  "valuations": [
    [p1d1],
    [p2d2, p2d3]
  ]
}