Skip to content

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,
        "hasParkingSpaces": 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: 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.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. Only one filter is accepted LocationFilter
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 in m2 ValueRange
filters.landArea Filter on land area in m2 ValueRange min: 50, max: 5'000
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 others: A .. G
filters.daysOnMarket Filter on days on market ValueRange
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
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 AT, BE, CH, CZ, DE, FR, JP, NL and SK are currently supported

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,
          "hasParkingSpaces": true,
          "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