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"
}'

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 enum mean, count, percentile or percentile_rank
statistics[i].metric enum 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 enum 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
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 Currency
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 Currency
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.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 AT, BE, CH, CZ, DE, FR and NL are currently supported

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 or days_on_market. 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
        }
      ]
    }
  ]
}

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