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 | 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": "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 |