Search By Property
POST /comparables/searchByProperty
Search for comparables by similarity to a comparison property.
Example Request
curl -X POST --location 'https://sandbox-comparables.realitycs.it/comparables/searchByProperty' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"Filters": {
"comparableTypeID": 1,
"contractTypeID": 1,
"propertyTypeID": 1,
"latitude": 45.464,
"longitude": 9.1895,
"rooms": 2,
"constructionYear": 1985,
"bathrooms": 3,
"elevator": false,
"maintenanceStatusID": 2,
"grossSquareFootage": 80,
"unitFloor": 0,
"energyClassID": 1,
"heatingSystemID": 1
},
"Pagination": {
"page": 1,
"limit": 10
},
"Sorting": {
"by": "ranking",
"direction": "desc"
}
}'
Request Fields
| Required column | Meaning |
|---|---|
| * | mandatory in the input |
| ** | at least one of these parameters is mandatory in the input |
| * | mandatory based on the value of another parameter |
| *** | optional parameter recommended for the reference property |
Filters
| Field | Required | Type | Example | Notes |
|---|---|---|---|---|
comparableTypeID | * | int / list[int] | 1 | Check Taxonomies General |
contractTypeID | * | int | 2 | depends on comparableTypeID |
propertyTypeID | * | int / list[int] | 1 | Check Taxonomies General |
latitude | * | float | 45.11 | |
longitude | * | float | 12.3 | |
rooms | *** | int | 3 | |
constructionYear | int | 1987 | ||
bathrooms | int | 2 | ||
elevator | bool | false | ||
maintenanceStatusID | *** | int | 3 | Check Taxonomies General |
grossSquareFootage | *** | int | 120 | |
unitFloor | *** | float | 1.0 | |
energyClassID | int | 5 | Check Taxonomies General | |
heatingSystemID | int | 2 | Check Taxonomies General | |
pubblicationStatusID | int / list[int] | [1,2] | Check Taxonomies General | |
minDate | string | 12/01/2025 | ||
maxDate | string | 25/09/2025 | ||
exclude_taxable | bool | This flag is optional and is set to true by default. This parameter is applicable exclusively to completed sales (Gold, Platinum or Bronze comparable types). When set to False, taxable counterparts of the requested comparableTypeID (3, 4, or 6) are also included in the returned results. In this context, a taxable sale (compravendita imponibile) reports as its price the statutory base used to calculate transaction taxes rather than the actual market transaction price. |
Pagination example usage
{
"Filters": {
... filters ...
},
"Pagination": {
"page": 1,
"limit": 10
}
}
Pagination filters
| filter | default | Type | Description |
|---|---|---|---|
| page | 1 | int | Shows results in the indicated page |
| limit | 5 | int | Sets the maximum number of results per page (can be configured differently if requested through sales) |
Sorting example usage
{
"Filters": {
... filters ...
},
"Sorting": {
"by": "date",
"direction": "desc"
}
}
Sorting filters
| filter | default | Type | Description |
|---|---|---|---|
| by | date | str | Orders the results by either ranking,energyclass or distance relative to a POI |
| direction | desc | str | List the results by ascending (asc) or descending (desc) order |
Example Response
{
"_metadata": {
"limit": 10,
"page": 1,
"pages": {
"first": 1,
"last": 233,
"next": 2,
"previous": null,
"self": 1
},
"query": {
"comparableType": "Offerta",
"contractType": "Vendita",
"grossSquareFootage": 80,
"latitude": 45.464,
"longitude": 9.1895,
"maintenanceStatus": "Ottimo / Ristrutturato",
"propertyType": "Appartamento",
"rooms": 2,
"sales": {
"municipalityID": 15146,
"nearestMunicipalityID": [],
"only_com": false
},
"sorting": {
"by": "ranking",
"direction": "desc"
},
"unitFloor": 0.0
},
"total_count": 2323,
"request_id": "4935503e-1ce9-41c4-b3bb-bec4d404054e",
"map": "http://sandbox-comparables.realitycs.it/map/4935503e-1ce9-41c4-b3bb-bec4d404054e"
},
"items": [
{
"_metadata": [
"comparabili_maintenancestatus_2",
"comparabili_comparabletype_1",
"comparabili_propertytype_1"
],
"askingPrice": 290000,
"askingPricePsm": 5800,
"balconycount": null,
"box_auto": null,
"comparableType": "Offerta",
"coverImage": "https://images.realitycs.it/img/107747375/1441487731",
"dataOwnership": "test",
"distance": 24,
"distanceFromPoi": null,
"elevator": null,
"energyClass": null,
"garden_type": null,
"grossSquareFootage": 50,
"grossSquareFootageDelta": 37.5,
"heatingsystem": null,
"maintenanceStatus": null,
"municipalityID": 15146,
"numberOfBathrooms": null,
"numberOfBuildingFloor": null,
"price": null,
"pricePsm": null,
"projUuid": null,
"propertyType": "Appartamento",
"rooms": null,
"salesDate": "2024-01-30T00:00:00Z",
"showCases": null,
"similarityRanking": 99.76,
"unitFloor": null,
"uri": "/comparable/fa0a3d44-0611-4e0e-8968-627efcbe475e",
"uuid": "fa0a3d44-0611-4e0e-8968-627efcbe475e",
"value": null,
"valuePsm": null
},
{
"_metadata": [
"comparabili_maintenancestatus_2",
"comparabili_comparabletype_1",
"comparabili_propertytype_1"
],
"askingPrice": 648000,
"askingPricePsm": 10800,
"balconycount": null,
"box_auto": null,
"comparableType": "Offerta",
"coverImage": "https://images.realitycs.it/img/124696163/1818965305",
"dataOwnership": "test",
"distance": 27,
"distanceFromPoi": null,
"elevator": null,
"energyClass": null,
"garden_type": null,
"grossSquareFootage": 60,
"grossSquareFootageDelta": 25,
"heatingsystem": null,
"maintenanceStatus": null,
"municipalityID": 15146,
"numberOfBathrooms": null,
"numberOfBuildingFloor": null,
"price": null,
"pricePsm": null,
"projUuid": null,
"propertyType": "Appartamento",
"rooms": null,
"salesDate": null,
"showCases": null,
"similarityRanking": 99.58,
"unitFloor": null,
"uri": "/comparable/2183e25f-d2a0-436d-9eef-13291daff487",
"uuid": "2183e25f-d2a0-436d-9eef-13291daff487",
"value": null,
"valuePsm": null
},
...
{
"_metadata": [
"comparabili_maintenancestatus_2",
"comparabili_comparabletype_1",
"comparabili_propertytype_1"
],
"askingPrice": 485000,
"askingPricePsm": 13472,
"balconycount": null,
"box_auto": null,
"comparableType": "Offerta",
"coverImage": "https://images.realitycs.it/img/79311245/901507657",
"dataOwnership": "test",
"distance": 79,
"distanceFromPoi": null,
"elevator": null,
"energyClass": null,
"garden_type": null,
"grossSquareFootage": 36,
"grossSquareFootageDelta": 55,
"heatingsystem": null,
"maintenanceStatus": null,
"municipalityID": 15146,
"numberOfBathrooms": null,
"numberOfBuildingFloor": null,
"price": null,
"pricePsm": null,
"projUuid": null,
"propertyType": "Appartamento",
"rooms": null,
"salesDate": "2021-05-27T00:00:00Z",
"showCases": null,
"similarityRanking": 98.82,
"unitFloor": null,
"uri": "/comparable/c198f388-59a1-4546-9110-04e45eb04150",
"uuid": "c198f388-59a1-4546-9110-04e45eb04150",
"value": null,
"valuePsm": null
}
]
}
N.B. The dates can be returned in the following two formats:
DD/MM/YYYYT00:00:00Z(default)DD/MM/YYYY
If you want to use the second format please make a request to the Sales team.