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
  }'

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
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": "https://quis.de/geo/53.56238135,9.91097785903008",
    "version": "2.5.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