Search 

POST /offers/search HTTP/2

The offer endpoint return offers, matching the specified search criteria for a region.

Example use-cases:

  • Display a filtered exposé list
  • Display the exposés on a map and interact with them
  • Calculate the average price or the average marketing duration
  • Get a similarity score for a given object and display the most similar offers on the market

Request 

curl -X POST 'https://quis.de/api/v2/offers/search?api_key=<YOUR-API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "dealType": "sale",
      "location": {
        "circle": {
          "center": {
            "address": {
              "unstructured": "Gasstraße 10, 22761 Hamburg"
            }
          },
          "radius": 3500
        }
      },
      "startDate": {
        "min": "2020-08-21"
      },
      "pricePerSqm": {
        "min": 5000.2,
        "max": 8000.2,
        "currency": "EUR"
      },
      "isFurnished": true
    },
    "referenceProperty": {
      "livingArea": 65.25,
      "buildingYear": 1975
    },
    "limit": 100
  }'
Field Description Type Remarks
filters Allows to specify various search criteria object  
filters.location Filters on a location LocationFilter  
filters.dealType Filter on offer’s deal type enum sale or rent
filters.propertyType Filter on offer’s property type array of PropertyType  
filters.startDate Filter on offer’s start date DateValueRange max is currently ignored
filters.endDate Filter on offer’s end date DateValueRange min is currently ignored
filters.price Filter on offer’s price PriceValueRange  
filters.pricePerSqm Filter on offer’s square meter price PriceValueRange based on the livingArea
filters.numberOfRooms Filter on offer’s number of rooms ValueRange  
filters.livingArea Filter on offer’s living area ValueRange  
filters.buildingYear Filter on offer’s building year ValueRange  
filters.isFurnished Filter on offer’s isFurnished flag boolean default: false
filters.isFirstOccupancy Filter on offer’s isFirstOccupancy flag boolean false is currently ignored
filters.isSubsidizedHousing Filter on offer’s isSubsidizedHousing flag boolean default: false
referenceProperty Reference property to calculate the similarity score ReferenceProperty  
limit Maximum number of results to return integer min: 0, max: 3.000, default: 3.000
offset Offset of the query (allows pagination) integer min: 0, max: 3.000, default: 0
orderBy Sort order array of OrderByCriterions  

LocationFilter

Either circle or divisionLevel100 needs to be provided

Field Description Type Remarks
circle Matches offers which lie within the circle defined by center and radius object Omits offers without coordinates
circle.center Center of the circle Location  
circle.radius Radius of the circle, in m integer min: 0, max: 10.000, default: 3.000
divisionLevel100 Matches offers within the level 100 division string Currently also handles raw addresses. However, use raw addresses with caution as this could change in the future without a deprecation warning.

OrderByCriterion

Field Description Type Remarks
field Field by which to sort enum distance, startDate, endDate, salePrice, salePricePerSqm, rentNet, rentNetPerSqm, livingArea, buildingYear, similarityScore
similarityScore will be applied after any other OrderByCriterion
direction Sort direction enum asc or desc, default: asc

ReferenceProperty

Field Description Type Remarks
livingArea Living area of the property float  
buildingYear Building year of the property integer  
landArea Land area of the property float  
price Price of the property float  

Response

Currently the number of items is capped at 3.000 items.

{
  "items": [
    {
      "id": "123456789",
      "dealType": "sale",
      "propertyType": {
        "type": "apartment",
        "subtype": "apartment_attic"
      },
      "source": "realestate.com",
      "startDate": "2020-08-23",
      "endDate": "2020-09-05",
      "marketDuration": "P13D5H",
      "images": [
        {
          "url": "https://s3.amazonaws.com/abc/123.jpg"
        }
      ],
      "location": {
        "address": {
          "street": "Gasstraße",
          "houseNumber": "10",
          "postCode": "22761",
          "city": "Hamburg"
        },
        "coordinates": {
          "latitude": 53.561262,
          "longitude": 9.9138307
        }
      },
      "distance": 250.92,
      "objectCondition": "Teil- oder vollrenoviert",
      "salePrice": 543210.58,
      "salePricePerSqm": 9053.51,
      "currency": "EUR",
      "floorNumber": 2,
      "numberOfRooms": 2.5,
      "buildingYear": 1975,
      "livingArea": 60.01,
      "availableFrom": "2020-10-01",
      "isFurnished": true,
      "hasBalconyOrTerrace": true,
      "similarityScore": 0.78
    }
  ],
  "totalItems": 1,
  "meta": {
    "url": null,
    "version": "2.14.0"
  }
}
Field Description Type Remarks
totalItems Total number of matching offers integer min: 0
This field is capped at 3.000 and is only accurate of there are less than 3.000 results. If there are more results, this field is equal 3.000.
items List of matching offers array of Offers empty array if no results
meta Meta information of the API Meta  

Offer

Field Description Type Remarks
id Technical ID of the offer string  
dealType Deal type of the offer enum sale or rent
propertyType Type of the property PropertyType  
source Source of the offer string domain format
startDate Date when the offer was first published Date  
endDate Date when the offer was last seen Date  
marketDuration The duration the offer has been published string ISO 8601 format
images Images of the offer array of URLs e.g. [{“url”: “https://s3.amazonaws.com/abc/123.jpg”}]
location Location of the property Location  
distance Distance to the requested circle center in meter float Only present if the requested location contains a circle
objectCondition The object condition desribed in the offer string As entered by the seller
salePrice Sale price of the offer float Only present if dealType is sale
salePricePerSqm Sale price per m2 of the offer float Only present if dealType is sale
rentNet Monthly net rent of the offer float Only present if dealType is rent
rentNetPerSqm Monthly net rent per m2 of the offer float Only present if dealType is rent
additionalCosts Additional costs of the offer (utilities, heating, water, etc.) float  
additionalCostsPerSqm Additional costs of the offer (utilities, heating, water, etc.) float  
currency Currency of the offer Currency  
floorNumber Floor number integer  
numberOfRooms Number of rooms of the property float  
buildingYear Building year of the property integer  
livingArea Living area of the property float  
landArea Land area of the property float  
usableArea Usable area of the property which is not included in the living area float  
availableFrom Date the property is available from. Date  
isFirstOccupancy Is the offer marked as the first occupancy? boolean e. g. after a renovation
isBarrierFree Is the property barrier-free? boolean e. g. accessible by a wheelchair
isFurnished Is the property furnished? boolean Includes complete and partial furnished objects
isSubsidizedHousing Is the property marked as subsidized housing? boolean  
hasKitchen Does the property have a fitted kitchen? boolean  
hasBalconyOrTerrace Does the property have a balcony or a terrace? boolean  
hasLift Does the building have a lift? boolean  
hasParkingSpace Does the property have a parking space? boolean  
hasUnderfloorHeating Does the property have underfloor heating? boolean  
similarityScore Similarity score Score Only returned if the request contains a reference object and the offer has all required fields

© 2020-2024 QUIS® ist ein Service der QUIS immo.analytics GmbH