Skip to content

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
    }
}
N.B. The pagination object can be omitted from the json body, and if so, the default limit and page will be used (see below)

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"
    }
}
N.B. The sorting object can be omitted from the json body, and if so, the default by and direction will be used (see below)

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.