Offer Search

POST offers/search

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=<YOU-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
  }'
FieldDescriptionTypeRemarks
filtersAllows to specify various search criteriaobject
filters.locationFilters on a locationLocationFilter
filters.dealTypeFilter on offer's deal typeenumsale or rent
filters.propertyTypeFilter on offer's property typearray of PropertyType
filters.startDateFilter on offer's start dateDateValueRangemax is currently ignored
filters.endDateFilter on offer's end dateDateValueRangemin is currently ignored
filters.priceFilter on offer's pricePriceValueRange
filters.pricePerSqmFilter on offer's square meter pricePriceValueRangebased on the livingArea
filters.numberOfRoomsFilter on offer's number of roomsValueRange
filters.livingAreaFilter on offer's living areaValueRange
filters.buildingYearFilter on offer's building yearValueRange
filters.isFurnishedFilter on offer's isFurnished flagbooleandefault: false
filters.isFirstOccupancyFilter on offer's isFirstOccupancy flagbooleanfalse is currently ignored
filters.isSubsidizedHousingFilter on offer's isSubsidizedHousing flagbooleandefault: false
referencePropertyReference property to calculate the similarity scoreReferenceProperty
limitMaximum number of results to returnintegermin: 0, max: 3.000, default: 3.000
offsetOffset of the query (allows pagination)integermin: 0, max: 3.000, default: 0
orderBySort orderarray of OrderByCriterions

LocationFilter

Either circle or divisionLevel100 needs to be provided

FieldDescriptionTypeRemarks
circleMatches offers which lie within the circle defined by center and radiusobjectOmits offers without coordinates
circle.centerCenter of the circleLocation
circle.radiusRadius of the circle, in mintegermin: 0, max: 10.000, default: 3.000
divisionLevel100Matches offers within the level 100 divisionstringCurrently also handles raw addresses. However, use raw addresses with caution as this could change in the future without a deprecation warning.

OrderByCriterion

FieldDescriptionTypeRemarks
fieldField by which to sortenumdistance, startDate, endDate, salePrice, salePricePerSqm, rentNet, rentNetPerSqm, livingArea, buildingYear, similarityScore
similarityScore will be applied after any other OrderByCriterion
directionSort directionenumasc or desc, default: asc

ReferenceProperty

FieldDescriptionTypeRemarks
livingAreaLiving area of the propertyfloat
buildingYearBuilding year of the propertyinteger
landAreaLand area of the propertyfloat
pricePrice of the propertyfloat

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": "https://quis.de/geo/53.56238135,9.91097785903008",
    "version": "2.4.1"
  }
}
FieldDescriptionTypeRemarks
totalItemsTotal number of matching offersintegermin: 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.
itemsList of matching offersarray of Offersempty array if no results
metaMeta information of the APIMeta

Offer

FieldDescriptionTypeRemarks
idTechnical ID of the offerstring
dealTypeDeal type of the offerenumsale or rent
propertyTypeType of the propertyPropertyType
sourceSource of the offerstringdomain format
startDateDate when the offer was first publishedDate
endDateDate when the offer was last seenDate
marketDurationThe duration the offer has been publishedstringISO 8601 format
imagesImages of the offerarray of URLse.g. [{"url": "https://s3.amazonaws.com/abc/123.jpg"}]
locationLocation of the propertyLocation
distanceDistance to the requested circle center in meterfloatOnly present if the requested location contains a circle
objectConditionThe object condition desribed in the offerstringAs entered by the seller
salePriceSale price of the offerfloatOnly present if dealType is sale
salePricePerSqmSale price per m2 of the offerfloatOnly present if dealType is sale
rentNetMonthly net rent of the offerfloatOnly present if dealType is rent
rentNetPerSqmMonthly net rent per m2 of the offerfloatOnly present if dealType is rent
additionalCostsAdditional costs of the offer (utilities, heating, water, etc.)float
additionalCostsPerSqmAdditional costs of the offer (utilities, heating, water, etc.)float
currencyCurrency of the offerCurrency
floorNumberFloor numberinteger
numberOfRoomsNumber of rooms of the propertyfloat
buildingYearBuilding year of the propertyinteger
livingAreaLiving area of the propertyfloat
landAreaLand area of the propertyfloat
usableAreaUsable area of the property which is not included in the living areafloat
availableFromDate the property is available from.Date
isFirstOccupancyIs the offer marked as the first occupancy?booleane. g. after a renovation
isBarrierFreeIs the property barrier-free?booleane. g. accessible by a wheelchair
isFurnishedIs the property furnished?booleanIncludes complete and partial furnished objects
isSubsidizedHousingIs the property marked as subsidized housing?boolean
hasKitchenDoes the property have a fitted kitchen?boolean
hasBalconyOrTerraceDoes the property have a balcony or a terrace?boolean
hasLiftDoes the building have a lift?boolean
hasParkingSpaceDoes the property have a parking space?boolean
hasUnderfloorHeatingDoes the property have underfloor heating?boolean
similarityScoreSimilarity scoreScoreOnly returned if the request contains a reference object and the offer has all required fields