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

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.

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

Request fields

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

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