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.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 a 2000m radius around the postcode center | 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 |
| 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": "moderate",
"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.15.0"
}
}
| Field | Description | Type | Remarks |
| totalItems | Total number of matching offers | integer | min: 0 |
| 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 described in the offer | enum | dilapidated, bad, moderate, good, very_good |
| 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 | float | |
| 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 |