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' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
  -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": 5000
        }
      }
    ],
    "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"
    }
  ],
  "dossierId": "3bac39b8-2d84-4ae9-a693-40502071ea5d",
  "countryCode": "CH"
}'

Field	Description	Type	Remarks
referenceLocation	Reference location of the search. Distances of offers are computed relative to this location	Location
dossierId	ID of the dossier	string	If this field is added to the request, then the referenceLocation must be the same as the dossierId's location (address or coordinates)
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: 24
filters.dealType	Filter on offer deal type	string	Valid values are 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.isFurnished	Filter on offer’s isFurnished flag	boolean	Only relevant for DE, FR and UK if filters.dealType is rent
filters.isNew	Filter on offer’s isNew flag	boolean
filters.isPrivate	Filter private offers with true or professional offers with false	boolean	Only relevant for DE, FR and BE
filters.salePrice	Filter on offer sale price	PriceValueRange	Only relevant if filters.dealType is sale
filters.rentGross	Filter on rent gross	PriceValueRange	Only relevant for AT, BE, CH, CZ, DE, ES, FR, JP, NL and SK if filters.dealType is rent
filters.rentNet	Filter on rent net	PriceValueRange	Only relevant for UK if filters.dealType is rent
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	ValueRange	In m2 For UK: in sq.ft
filters.landArea	Filter on land area	ValueRange	In m2 For UK: in acres
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	Only for apartments. Only relevant for BE, CH, CZ, DE, SK
filters.numberOfBathrooms	Filter on number of bathrooms	ValueRange	Only relevant for AT, BE, FR, DE, NL, UK
filters.buildingYear	Filter on building year	ValueRange	Not available in UK
filters.numberOfRooms	Filter on number of rooms	FloatValueRange	Not relevant in BE, UK
filters.hasOpenKitchen	Whether the kitchen is in a separate room or part of the living area	boolean	Only relevant for CZ
filters.numberOfBedrooms	Filter on number of bedrooms	ValueRange	Only available in BE, UK
filters.buildingStructure	Filter on building structure	array of Building Structures	Only relevant in JP
filters.roomConfiguration	Filter on room configuration	array of Room configurations	Only relevant in JP
filters.daysOnMarket	Filter on days on market	ValueRange
filters.noise	Upper and lower 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	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.hasLift	Filter on the offer's hasLift flag	boolean
filters.hasParkingSpaces	Filter on the offer's hasParkingSpaces flag	boolean
filters.propertyCondition	Filter on propertyCondition	array of Conditions	Only relevant in AT, BE, CZ, DE, SK
filters.numberOfFloorsInBuilding	Filter on numberOfFloorsInBuilding	ValueRange	Only for apartment. Only relevant in BE, NL
filters.isWheelchairAccessible	Filter on the offer's isWheelchairAccessible flag	boolean
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
locale	User locale	string

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
divisionLevel4	The official ID of the level 4 division	string	Only relevant for SK
divisionLevel6	The official ID of the level 6 division	string
divisionLevel8	The official ID of the level 8 division	string
divisionLevel9	The official ID of the level 9 division	string	Only relevant for SK
divisionLevel100	The official ID of the level 100 division	string

OrderByCriterion

Field	Description	Type	Remarks
field	Field by which to sort	string	Valid values are distance, startDate, salePrice, rentGross, rentNet, salePricePerSqm, rentGrossPerSqm or rentNetPerSqm
direction	Sort direction	string	Valid values are asc (default) or desc

Response

{
  "items": [
    {
      "offerId": "c41924a0fb86b4e2e2da33f2ff468b72f2...",
      "dealType": "sale",
      "startDate": "2018-07-31",
      "isActive": true,
      "isFurnished": false,
      "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,
    },
    ...
  ],
  "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	string	Valid values are 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
isPrivate	true if the offer is private, false if the offer is professional, not present if unknown	boolean
isFurnished	true if the offer is furnished, false if not	boolean	Only relevant for DE, FR and UK if filters.dealType is rent
title	Title of the offer	string
description	Description of the offer	string
images	Images of the offer	array of URLs	e.g. [{"url": "https://storage.googleapis.com/abc/b787e.jpg"}]
contactInfo	Contact information for the offer	object	Possible subfields: raw, organization.raw, viewPerson.raw, inquiryPerson.raw
isExclusive	Is the offer exclusively published on one website	boolean
url	Original url of the offer ad	string
salePrice	Sale price of the offer	integer	Only present if dealType is sale
salePricePerSqm	Sale price per m2, per sq.ft for UK	integer	Only present if dealType is sale
rentNet	Monthly net rent of the offer	integer	Only present if dealType is rent
rentNetPerSqm	Monthly net rent per m2 of the offer	integer	Only present if dealType is rent
rentGross	Monthly gross rent of the offer	integer	Only present if dealType is rent
rentGrossPerSqm	Monthly gross rent per m2 of the offer	integer	Only present if dealType is rent
currency	Currency of the offer	Currency
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
renovationYear	Renovation year of the property	integer	Only relevant in DE
propertyType	Type of the property	PropertyType
livingArea	Net living area (SIA standard) of the property	integer	In m2 For UK: in sq.ft
landArea	Total area of the lot/parcel on which the house is standing	integer	In m2 For UK: in acres
volume	Volume of the property (house)	integer	In m3 For UK: in cu.ft
numberOfRooms	Number of rooms of the property	float
energyLabel	Energy label of the property	Energy label	Only relevant in BE, DE, FR, NL and UK
hasOpenKitchen	Whether the kitchen is in a separate room or part of the living area	boolean	Only relevant for CZ
hasCellar	Whether the property has a cellar	boolean	Only available in CZ, DE, FR, SK
numberOfBedrooms	Number of bedrooms of the property	integer	Only relevant in BE
numberOfBathrooms	Number of bathrooms of the property	integer	Only relevant in DE
buildingStructure	Building structure	Building Structure	Only relevant in JP and SK
roomConfiguration	Room configuration	Room Configuration	Only relevant in JP
propertyCondition	General condition of the property	Condition	Only relevant in AT, BE, CZ, DE, SK
numberOfFloorsInBuilding	Total number of floors of the building	integer	Only for apartment. Only relevant in BE, NL
domesticEquipmentQuality	Quality of the equipment in the property	string	Only relevant in DE
facilityItems	List of facility items	string	Only relevant in JP
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	Only available in AT, BE, CH, CZ, DE, FR, NL, SK
hasParkingSpaces	Does the property have parking spaces?	boolean	Only available in AT, BE, CH, CZ, FR, NL, SK
hasTerrace	Does the property have a terrace?	boolean	Only available in CH, DE, FR
hasBalcony	Does the property have a balcony?	boolean	Only available in CH, CZ, DE
hasPool	Does the property have a pool?	boolean	Only available in BE
hasGarden	Does the property have a garden?	boolean	Only available in CZ, DE, FR, NL, SK
isWheelchairAccessible	Is the property wheelchair accessible?	boolean
numberOfIndoorParkingSpaces	Number of indoor parking spaces	integer
numberOfOutdoorParkingSpaces	Number of outdoor parking spaces	integer
priceUpdates	List of price updates	priceUpdate

Price Update

Field	Description	Type	Remarks
price	Price of the property	float
date	Date of the update	string	Formatted as YYYY-MM-DD