Skip to content

Offer Search

POST offers/search

Returns offers that match the specified search criteria.

Request#

curl -X POST 'https://api.pricehubble.com/api/v1/offers/search?access_token=74126eab0a9048d993bda4b1b55ae074' \
  -H 'Content-Type: application/json' \
  -d '{
  "referenceLocation": {
    "address": {
      "city": "Zurich",
      "houseNumber": "19",
      "postCode": "8001",
      "street": "Gerechtigkeitsgasse"
    }
  },
  "filters": {
    "dealType": "sale",
    "startDate": {
      "min": "2018-01-01"
    },
    "isActive": true,
    "salePrice": {
      "currency": "CHF",
      "max": 1000000
    },
    "location": [
      {
        "circle": {
          "center": {
            "coordinates": {
              "latitude": 47.36925,
              "longitude": 8.531118
            }
          },
          "radius": 30000
        }
      }
    ],
    "propertyType": [
      {
        "code": "apartment",
        "subcode": "apartment_normal"
      },
      {
        "code": "apartment",
        "subcode": "apartment_attic"
      }
    ],
    "livingArea": {
      "min": 80,
      "max": 110
    },
    "numberOfRooms": {
      "min": 4,
      "max": 4.5
    },
    "hasLift": true,
    "hasParkingSpaces": true
  },
  "offset": 0,
  "limit": 10,
  "orderBy": [
    {
      "field": "distance"
    },
    {
      "field": "startDate",
      "direction": "desc"
    }
  ],
  "countryCode": "CH"
}'
Field Description Type Remarks
referenceLocation Reference location of the search. Distances of offers are computed relative to this location Location
filters Allows to specify various search criteria object
filters.offerIds IDs of offers returned in a previous call (see response.items[i].offerId); can be used to get the latest state of the respective offers array of strings min items: 0, max items: 10
filters.dealType Filter on offer deal type enum sale or rent; required unless offerIds is specified
filters.startDate Filter on offer start date object
filters.startDate.min Lower bound for offer start date date Date format: YYYY-MM-DD
filters.startDate.max Upper bound for offer start date date Date format: YYYY-MM-DD
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.location Filters on location. If multiple filters are provided, they are connected by a logical "or" array of LocationFilters
filters.propertyType Filter on property type. Matches offers which have one of the specified property types array of PropertyTypes
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.landArea Filter on land area object
filters.landArea.min Lower bound for land area, in m2 integer min: 50, max: 5'000
filters.landArea.max Upper bound for land area, in m2 integer min: 50, max: 5'000
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.noise.min Lower bound for noise score Score Only available in CH.
filters.noise.max Upper bound for noise score Score Only available in CH.
filters.slope.min Lower bound for slope, in degrees integer min: 0, max: 90
Only available in CH.
filters.slope.max Upper bound for slope, in degrees integer min: 0, max: 90
Only available in CH.
filters.distanceHospital.max Upper bound for the distance to the closest hospital POI, in meters integer max: 2'000
filters.distanceGroceryStore.max Upper bound for the distance to the closest grocery store POI, in meters integer max: 2'000
filters.distancePublicTransport.max Upper bound for the distance to the closest public transport POI, in meters integer max: 2'000
filters.hasLift Filter on the offer's hasLift flag boolean
filters.hasParkingSpaces Filter on the offer's hasParkingSpaces flag boolean
filters.isWheelchairAccessible Filter on the offer's isWheelchairAccessible flag boolean
includeShareableLinks Return shareable links to PriceHubble Dash? boolean default: false
Shareable links are currently only supported for CH country and sale deal type.
offset Offset of the query (allows pagination) integer min: 0, max: 1'000, default: 0
limit Maximum number of results to return integer min: 0, max: 500, default: 10
orderBy Sort order array of OrderByCriterions
countryCode ISO country code string CH, DE, FR and NL are currently supported
locale User locale string Required if includeShareableLinks is set to true

LocationFilter#

To filter by location, either a circle or a divisionLevel* must be provided. If you would like to filter by division levels but 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
circle Location filter of type "circle". Matches offers which lie within the circle defined by center and radius object
circle.center Center of the circle Location
circle.radius Radius of the circle, in m integer min: 0, max: 30'000, default: 20'000
divisionLevel6 The official ID of the level 6 division string
divisionLevel8 The official ID of the level 8 division string
divisionLevel100 The official ID of the level 100 division string

OrderByCriterion#

Field Description Type Remarks
field Field by which to sort enum distance, startDate, salePrice or rentGross
direction Sort direction enum asc (default) or desc

Response#

{
  "items": [
    {
      "offerId": "c41924a0fb86b4e2e2da33f2ff468b72f2...",
      "dealType": "sale",
      "startDate": "2018-07-31",
      "isActive": true,
      "isNew": true,
      "title": "Wohnen mit Aus- und Weitsicht",
      "description": "An toller Lage, angrenzend an die Landwirtschafts-...",
      "images": [
        {
          "url": "https://storage.googleapis.com/.../...b7879b37e.jpg"
        },
        {
          "url": "https://storage.googleapis.com/.../...0f771be42.jpg"
        }
      ],
      "contactInfo": {
         "organization": {
           "raw": "Bachmann & Partner Immobilien\nEglisau\n\n\n044 854 00 00"
         }
      },
      "isExclusive": false,
      "url": "https://example.org/realestate/offers/123",
      "salePrice": 490000,
      "currency": "CHF",
      "address": {
        "city": "Oberglatt",
        "houseNumber": "1",
        "postCode": "8154",
        "street": "Allmendstrasse"
      },
      "coordinates": {
        "latitude": 47.4741020202637,
        "longitude": 8.51667785644531
      },
      "distance": 11708,
      "floorNumber": 2,
      "buildingYear": 1971,
      "propertyType": {
        "code": "apartment",
        "subcode": "apartment_normal"
      },
      "livingArea": 95,
      "numberOfRooms": 4.5,
      "hasLift": true,
      "hasParkingSpaces": true,
      "numberOfIndoorParkingSpaces": 0,
      "numberOfOutdoorParkingSpaces": 1,
      "shareableLink": "https://dash.pricehubble.com/shared/offer/3e545020-fc94-4458-957a-9ab6caee4d2b/"
    },
    ...
  ],
  "totalItems": 18
}
Field Description Type Remarks
totalItems Total number of matching offers found integer min: 0
This field is capped and is only accurate if there are less than 1’500 results. If there are more results, this field will equal 1’500
items List of matching offers array of Offers empty array if no results

Offer#

Field Description Type Remarks
offerId Technical ID of the offer string
dealType Deal type of the offer enum sale or rent
startDate Start date of the offer, i.e. date when the offer was first published date Format: YYYY-MM-DD
endDate End date of the offer, i.e. date when the offer disappeared from the market; only set for historical (inactive) offers date Format: YYYY-MM-DD
daysOnMarket Number of days that the offer has stayed on the market integer
isActive Is the offer still active, i.e. is the property still available? boolean
isNew Has the property never been used before, i.e. has it never been sold or rented out? boolean
title Title of the offer string
description Description of the offer string
images Images of the offer array
contactInfo Contact information for the offer object Possible subfields: raw, organization.raw, viewPerson.raw, inquiryPerson.raw
isExclusive Is the offer exclusively published on the PriceHubble API? boolean
url Original url of the offer ad string
salePrice Sale price of the offer integer Only present if dealType is sale
rentNet Monthly net rent of the offer integer Only present if dealType is rent
rentGross Monthly gross rent of the offer integer Only present if dealType is rent
currency Currency of the offer string CHF or EUR
address Address of the property Address
coordinates Coordinates of the property Coordinates
distance Distance of the property to the reference location, in m integer Only returned if the request contains a referenceLocation
distanceHospital Distance to the closest hospital POI, in m integer Only returned if the request contains filters.distanceHospital.max
distanceGroceryStore Distance to the closest grocery store POI, in m integer Only returned if the request contains filters.distanceGroceryStore.max
distancePublicTransport Distance to the closest public transport POI, in m integer Only returned if the request contains filters.distancePublicTransport.max
floorNumber Floor number integer
buildingYear Building year of the property integer
propertyType Type of the property PropertyType
livingArea Net living area (SIA standard) of the property, in m2 integer
landArea Total area of the lot/parcel on which the house is standing, in m2 integer
volume Volume of the property (house), in m3 integer
numberOfRooms Number of rooms of the property float
noise Property area noise levels score Score min: 0.0, max: 1.0
Only returned if the request contains noise filter
slope Property area slope, in degrees float min: 0.0, max: 90.0
Only returned if the request contains slope filter
hasLift Does the building have a lift? boolean
hasParkingSpaces Does the property have parking spaces? boolean
isWheelchairAccessible Is the property wheelchair accessible? boolean
numberOfIndoorParkingSpaces Number of indoor parking spaces integer
numberOfOutdoorParkingSpaces Number of outdoor parking spaces integer
shareableLink Shareable link to PriceHubble Dash. The UI language can be set by adding the suffix ?lang=en to the shareable link (Supported languages: de, en, fr, it, ja) string