Offer Statistics
POST
offers/statistics
Returns offer statistics for the specified administrative division and time period. For example, average yearly offer prices in Zurich for a time period between 2010 and 2014 can be obtained.
Statistics can only be obtained for one administrative division at a time. If you want to obtain statistics for multiple administrative divisions, you need to make multiple calls.
Request#
Example Request 1#
curl -X POST 'https://api.pricehubble.com/api/v1/offers/statistics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
-d '{
"statistics": [
{
"metric": "rent_gross",
"type": "mean"
},
{
"metric": "rent_gross",
"type": "count"
},
{
"metric": "rent_gross",
"type": "percentile",
"parameters": {
"percentileRank": 50
}
},
{
"metric": "rent_gross",
"type": "percentile_rank",
"parameters": {
"percentileValue": 2350
}
},
{
"metric": "rent_gross",
"type": "percentile_rank",
"parameters": {
"percentileValue": 2580
}
},
{
"metric": "days_on_market",
"type": "percentile",
"parameters": {
"percentileRank": 50
}
},
{
"metric": "energy_label",
"type": "count"
}
],
"filters": {
"dealType": "rent",
"propertyType": "apartment",
"divisionLevel100": "8001",
"startDate": {
"min": "2017-01",
"max": "2018-12"
}
},
"countryCode": "CH"
}'
Example Request 2 (group by year)#
curl -X POST 'https://api.pricehubble.com/api/v1/offers/statistics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
-d '{
"statistics": [
{
"metric": "rent_gross",
"type": "count"
}
],
"groupBy": {
"field": "start_date",
"period": "year"
},
"filters": {
"dealType": "rent",
"propertyType": "apartment",
"divisionLevel100": "8001",
"startDate": {
"min": "2017-01",
"max": "2018-12"
}
},
"countryCode": "CH"
}'
Example Request 3 (group by price)#
curl -X POST 'https://api.pricehubble.com/api/v1/offers/statistics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
-d '{
"statistics": [
{
"metric": "rent_gross",
"type": "count"
}
],
"groupBy": {
"field": "rent_gross",
"groups": [
{
"upperBound": 1000
},
{
"lowerBound": 1000,
"upperBound": 2000
},
{
"lowerBound": 2000
}
]
},
"filters": {
"dealType": "rent",
"propertyType": "apartment",
"divisionLevel100": "8001",
"startDate": {
"min": "2017-01",
"max": "2018-12"
}
},
"dossierId": "3bac39b8-2d84-4ae9-a693-40502071ea5d",
"countryCode": "CH"
}'
Offer Statistics Request#
Exactly one divisionLevel* must be provided. If you only have an address or coordinates and don't know the official ID of the administrative division, you can use the Administrative Divisions endpoint to look up the administrative division and the respective ID.
Field | Description | Type | Remarks |
---|---|---|---|
statistics | array of objects | ||
statistics[i].type | string | Valid values are mean , count , percentile or percentile_rank .When using energy_label metric, statistics[i].type must be count . |
|
statistics[i].metric | string | Offer Statistics Metrics | |
statistics[i].parameters | object | Parameters for the chosen statistic type, currently only required by percentile & percentile_rank . |
|
statistics[i].parameters.percentileRank | integer | - min: 0, max: 100 Only required by percentile statistic type (try 25 , 50 , 75 or 95 to get the 25th, 50th (median), 75th or 95th percentiles) |
|
statistics[i].parameters.percentileValue | integer | - min: 0 Only required by percentile_rank statistic type (the percentile rank of a value relative to the list of all values) |
|
groupBy | object | ||
groupBy.field | The field by which to group the results | string | Valid values are Offer Statistics Metrics or start_date or end_date |
groupBy.groups | List of explicit groups | array | required if groupBy.field is an Offer Statistics Metrics; min items: 1, max items: 24 |
groupBy.groups[i] | object | Either lowerBound or upperBound is required for all groupBy.field metrics except energy_label .value is required when groupBy.field is energy_label . |
|
groupBy.groups[i].lowerBound | float or integer | ||
groupBy.groups[i].upperBound | float or integer | upperBound is excluded of the group. That way upperBound of one group can be the lowerBound of the next group. | |
groupBy.groups[i].value | one of Energy label | required if groupBy.field is energy_label , available values are country-specific. Only relevant for BE , DE , FR , NL , UK |
|
groupBy.period | string | Valid values are month , quarter or year ; required if groupBy.field is start_date or end_date |
|
filters | object | ||
filters.dealType | string | Valid values are sale or rent |
|
filters.startDate | Filter on the offers' start date (= first publishing date) | object | Required if groupBy.field is start_date .One of filters.startDate or filters.endDate is required. |
filters.startDate.min | string | Format: YYYY-MM | |
filters.startDate.max | string | Format: YYYY-MM | |
filters.endDate | Filter on the offers' end date (= last date on the market) | object | Required if groupBy.field is end_date .One of filters.startDate or filters.endDate is required. |
filters.endDate.min | string | Format: YYYY-MM | |
filters.endDate.max | string | Format: YYYY-MM | |
filters.coordinates | Filter by location from the given set of coordinates | Coordinates | Requires filters.radius to be passed along |
filters.radius | Radius of the location filter, in m | integer | min: 0, max: 10'000 Requires filters.coordinates to be passed along |
filters.isActive | Filter on offer's isActive flag |
boolean | |
filters.isNew | Filter on offer's isNew flag |
boolean | |
filters.isPrivate | Filter private offers with true or professional offers with false |
boolean | |
filters.salePrice | Filter on offer sale price | object | Only relevant if filters.dealType is sale |
filters.salePrice.currency | Currency of the sale price filter | Currency | |
filters.salePrice.min | Lower bound for offer sale price | integer | |
filters.salePrice.max | Upper bound for offer sale price | integer | |
filters.propertyCondition | General condition of the property | array of Conditions | Only relevant in AT , BE , CZ , DE , SK |
filters.numberOfFloorsInBuilding | Total number of floors of the building | ValueRange | Only for apartment . Only relevant in BE , NL |
filters.energyLabel | Filter on energy label | array of Energy labels | Only relevant for BE , DE , FR , NL , UK |
filters.floorNumber | Filter on floor number | ValueRange | |
filters.numberOfBathrooms | Filter on number of bathrooms | ValueRange | |
filters.rentGross | Filter on rent gross | object | Only relevant if filters.dealType is rent |
filters.rentGross.currency | Currency of the rent gross filter | Currency | |
filters.rentGross.min | Lower bound for rent gross | integer | |
filters.rentGross.max | Upper bound for rent gross | integer | |
filters.propertyType | string | Valid values are apartment or house |
|
filters.livingArea | Filter on net living area | object | |
filters.livingArea.min | Lower bound for net living area | integer | In m2 For UK : in sq.ft |
filters.livingArea.max | Upper bound for net living area | integer | In m2 For UK : in sq.ft |
filters.buildingYear | Filter on building year | object | |
filters.buildingYear.min | Lower bound for building year | integer | |
filters.buildingYear.max | Upper bound for building year | integer | |
filters.numberOfRooms | Filter on number of rooms | object | Not relevant in BE , UK |
filters.numberOfRooms.min | Lower bound for number of rooms | float | |
filters.numberOfRooms.max | Upper bound for number of rooms | float | |
filters.numberOfBedrooms | Filter on number of bedrooms | object | Only available in BE , UK |
filters.numberOfBedrooms.min | Lower bound for number of bedrooms | float | |
filters.numberOfBedrooms.max | Upper bound for number of bedrooms | float | |
filters.hasLift | Filter on the offer's hasLift flag |
boolean | Only available in AT , BE , CH , CZ , DE , FR , NL , SK |
filters.hasParkingSpaces | Filter on the offer's hasParkingSpaces flag |
boolean | Only available in AT , BE , CH , CZ , FR , NL , SK |
filters.hasTerrace | Filter on the offer's hasTerrace flag |
boolean | Only available in CH , DE , FR |
filters.hasCellar | Filter on offer's hasCellar flag |
boolean | Only available in CZ , DE , FR |
filters.hasBalcony | Filter on offer's hasBalcony flag |
boolean | Only available in CH , CZ , DE |
filters.hasPool | Filter on offer's hasPool flag |
boolean | Only available in BE |
filters.hasGarden | Filter on offer's hasGarden flag |
boolean | Only available in CZ , DE , FR , NL , SK |
filters.hasOpenKitchen | Whether the kitchen is in a separate room or part of the living area | boolean | Only relevant for CZ |
filters.daysOnMarket | Filter on days on market | object | |
filters.daysOnMarket.min | Lower bound for days on market | integer | |
filters.daysOnMarket.max | Upper bound for days on market | integer | |
filters.divisionLevel4 | The official ID of the level 4 division | string | Only relevant for SK |
filters.divisionLevel6 | The official ID of the level 6 division | string | |
filters.divisionLevel8 | The official ID of the level 8 division | string | |
filters.divisionLevel9 | The official ID of the level 9 division | string | Only relevant for SK |
filters.divisionLevel100 | The official ID of the level 100 division | string | |
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 |
Offer Statistics Metrics#
The possible metrics are: sale_price
, sale_price_per_square_meter
, rent_gross
, rent_gross_per_square_meter
, rent_net
, rent_net_per_square_meter
, living_area
, number_of_rooms
, days_on_market
or energy_label
. number_of_bedrooms
but only available in BE
, UK
Response#
Example Response 1#
{
"items": [
{
"statistics": [
{
"metric": "rent_gross",
"type": "mean",
"value": 3170.22
},
{
"metric": "rent_gross",
"type": "count",
"value": 630
},
{
"metric": "rent_gross",
"type": "percentile",
"parameters": {
"percentileRank": 50
},
"value": 2840.0
},
{
"metric": "rent_gross",
"type": "percentile_rank",
"parameters": {
"percentileValue": 2350
},
"value": 33.81
},
{
"metric": "rent_gross",
"type": "percentile_rank",
"parameters": {
"percentileValue": 2580
},
"value": 42.22
},
{
"metric": "days_on_market",
"type": "percentile",
"parameters": {
"percentileRank": 50
},
"value": 14.0
},
{
"metric": "energy_label",
"type": "count",
"value": 14
}
]
}
]
}
Example Response 2 (group by year)#
{
"items": [
{
"groupId": "2017",
"statistics": [
{
"metric": "rent_gross",
"type": "count",
"value": 229
}
]
},
{
"groupId": "2018",
"statistics": [
{
"metric": "rent_gross",
"type": "count",
"value": 401
}
]
}
]
}
Example Response 3 (group by price)#
{
"items": [
{
"groupId": "0",
"groupUpperBound": 1000,
"statistics": [
{
"metric": "rent_gross",
"type": "count",
"value": 27
}
]
},
{
"groupId": "1",
"groupLowerBound": 1000,
"groupUpperBound": 2000,
"statistics": [
{
"metric": "rent_gross",
"type": "count",
"value": 137
}
]
},
{
"groupId": "2",
"groupLowerBound": 2000,
"statistics": [
{
"metric": "rent_gross",
"type": "count",
"value": 466
}
]
}
]
}
Offer Statistics Response#
Prices are returned in the country's main currency. Rents are per month.
Field | Description | Type | Remarks |
---|---|---|---|
items | List of statistics; per “group" if grouping was requested | array of objects | If grouping by start_date or end_date was requested, the list is sorted by time in ascending order and the length of the array is equal to the number of periods between request.filters.startDate.min and request.filters.startDate.max or between request.filters.endDate.min and request.filters.endDate.max ; if any other grouping was requested the order corresponds to the order of the groups in the request (i.e. the order of request.groupBy.groups ) and the length of the array is equal to the length of request.groupBy.groups |
items[i].groupId | string | E.g. "2018-01", "2018-Q1" or "2018" if grouping by start_date or end_date was requested, or the (zero-based) index of the group (as a string) if any other grouping was requested |
|
items[i].groupLowerBound | float or integer | Corresponds to what was set in request.groupBy.groups[i].lowerBound |
|
items[i].groupUpperBound | float or integer | Corresponds to what was set in request.groupBy.groups[i].upperBound |
|
items[i].groupValue | string | Corresponds to what was set in request.groupBy.groups[i].value |
|
items[i].statistics | array of objects | ||
items[i].statistics[i].type | string | Valid values are mean , count , percentile or percentile_rank |
|
items[i].statistics[i].metric | string | Offer Statistics Metrics | |
items[i].statistics[i].parameters | Parameters for the chosen statistic type, if provided in the request | object | |
items[i].statistics[i].value | Value of the requested statistic | float or integer | Not set if there is not enough data to compute the requested statistic for the requested group |