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 m² For `UK`: in sq.ft
filters.livingArea.max	Upper bound for net living area	integer	In m² 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