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?access_token=74126eab0a9048d993bda4b1b55ae074' \
  -H 'Content-Type: application/json' \
  -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
            }
        }
    ],
    "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?access_token=74126eab0a9048d993bda4b1b55ae074' \
  -H 'Content-Type: application/json' \
  -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?access_token=74126eab0a9048d993bda4b1b55ae074' \
  -H 'Content-Type: application/json' \
  -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"
}'

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 enum mean, count, percentile or percentile_rank
statistics[i].metric enum 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 or days_on_market
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 enum 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, start_date or days_on_market
groupBy.groups List of explicit groups array required if groupBy.field is 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 or days_on_market; min items: 1, max items: 24
groupBy.groups[i] object Either lowerBound or upperBound is required
groupBy.groups[i].lowerBound float or integer
groupBy.groups[i].upperBound float or integer
groupBy.period enum month, quarter or year; required if groupBy.field is start_date
filters object
filters.dealType enum 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.salePrice Filter on offer sale price object Only relevant if filters.dealType is sale
filters.salePrice.currency Currency of the sale price filter string CHF or EUR
filters.salePrice.min Lower bound for offer sale price integer
filters.salePrice.max Upper bound for offer sale price integer
filters.rentGross Filter on rent gross object Only relevant if filters.dealType is rent
filters.rentGross.currency Currency of the rent gross filter string CHF or EUR
filters.rentGross.min Lower bound for rent gross integer
filters.rentGross.max Upper bound for rent gross integer
filters.propertyType enum apartment or house
filters.livingArea Filter on net living area object
filters.livingArea.min Lower bound for net living area, in m2 integer
filters.livingArea.max Upper bound for net living area, in m2 integer
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.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 AT, CH, DE, FR and NL are currently supported

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
        }
      ]
    }
  ]
}

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
        }
      ]
    }
  ]
}

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].statistics array of objects
items[i].statistics[i].type enum mean, count, percentile or percentile_rank
items[i].statistics[i].metric enum 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 or days_on_market
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