Exclusive Offer Search
POST comparables/exclusive/offers/search
Returns exclusive offers that match the specified search criteria.
Request#
curl -X POST 'https://api.pricehubble.com/api/v1/comparables/exclusive/offers/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 74126eab0a9048d993bda4b1b55ae074' \
-d '{
"referenceLocation": {
"address": {
"city": "Berlin",
"houseNumber": "30",
"postCode": "10779",
"street": "Heilbronner Str."
}
},
"filters": {
"dealType": "sale",
"isActive": true,
"salePrice": {
"currency": "EUR",
"max": 1000000
},
"location": [
{
"circle": {
"center": {
"coordinates": {
"latitude": 52.49303,
"longitude": 13.34087
}
},
"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
},
"offset": 0,
"limit": 10,
"orderBy": [
{
"field": "distance"
},
{
"field": "startDate",
"direction": "desc"
}
],
"countryCode": "DE"
}'
| 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 | Source IDs of offers created earlier (see response.items[i].sourceOfferId); |
array of strings | min items: 0, max items: 24 |
| 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.isFurnished | Filter on offer’s isFurnished flag |
boolean | Only relevant for DE and FR if filters.dealType is rent |
| filters.isPrivate | Filter private offers with true or professional offers with false |
boolean | |
| filters.salePrice | Filter on offer sale price | PriceValueRange | Only relevant if filters.dealType is sale |
| filters.rentGross | Filter on rent gross | PriceValueRange | Only relevant 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.buildingYear | Filter on building year | ValueRange | |
| filters.numberOfRooms | Filter on number of rooms | FloatValueRange | |
| filters.energyLabel | Filter on energy label | array of enum | For DE: A++, A+, A .. H. For NL: A+++, A++, A+, A .. G. For BE: A++, A+, A .. G. For others: A .. G. Format a_plus_plus, a_plus, ... h is also allowed. |
| filters.daysOnMarket | Filter on days on market | ValueRange | |
| filters.hasLift | Filter on the offer's hasLift flag |
boolean | |
| filters.hasBalcony | Filter on the offer's hasBalcony flag |
boolean | |
| filters.hasIndoorParkingSpaces | Filter on the offer's hasIndoorParkingSpaces flag |
boolean | |
| filters.hasOutdoorParkingSpaces | Filter on the offer's hasOutdoorParkingSpaces flag |
boolean | |
| 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 |
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 | enum | distance, startDate, salePrice, rentGross, daysOnMarket, salePricePerSqm, rentGrossPerSqm or rentNetPerSqm |
| direction | Sort direction | enum | asc (default) or desc |
Response#
{
"items": [
{
"offerId": "5de5ef17-1742-4aad-a5dd...",
"countryCode": "DE",
"sourceOfferId": "c8d35a6f-997d-454b-bf26...",
"title": "Schmuckstück über den Dächern Berlins zur Eigennutzung",
"description": "Die sehr schöne und helle 2-Zimmerwohnung...",
"images": [
{
"url": "https://storage.googleapis.com/.../...b7879b37e.jpg",
"filename": "...b7879b37e.jpg"
},
{
"url": "https://storage.googleapis.com/.../...b0030b68e.jpg",
"filename": "...b0030b68e.jpg"
}
],
"property": {
"location": {
"address": {
"city": "Berlin",
"houseNumber": "1",
"postCode": "10781",
"street": "Traunsteiner Str."
},
"coordinates": {
"latitude": 52.4930554287132,
"longitude": 13.3454089228098
}
},
"propertyType": {
"code": "apartment",
"subcode": "apartment_normal"
},
"livingArea": 100,
"buildingYear": 1971,
"numberOfRooms": 4.5,
"numberOfIndoorParkingSpaces": 0,
"numberOfOutdoorParkingSpaces": 1,
"floorNumber": 4,
"hasLift": true,
"isNew": true,
"isFurnished": true
},
"offer": {
"startDate": "2018-07-31",
"daysOnMarket": 35,
"dealType": "sale",
"salePrice": 490000,
"salePricePerSqm": 4900,
"isActive": true,
"currency": "EUR"
},
"distance": 313
},
...
],
"totalItems": 5
}
| 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 |