Skip to content

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"
        }
    },
    "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
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
groupBy.period string Valid values are month, quarter or year; required if groupBy.field is start_date
filters object
filters.dealType string Valid values are sale or rent
filters.startDate Filter on the offers' start date (= first publishing date) object
filters.startDate.min string Format: YYYY-MM
filters.startDate.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
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
filters.numberOfRooms.min Lower bound for number of rooms float
filters.numberOfRooms.max Upper bound for number of rooms 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.divisionLevel6 The official ID of the level 6 division string
filters.divisionLevel8 The official ID of the level 8 division string
filters.divisionLevel100 The official ID of the level 100 division string
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

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 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; 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 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