Search By Attribute

POST /comparables/searchByAttribute

Search for comparables based on filters relating to the comparable's descriptive attributes. It allows you to search for both Asking comparables and Sale (contract-based) comparables.

Example Request

curl -X POST 'https://sandbox-comparables.realitycs.it/comparables/searchByAttribute' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
--data-raw '{
    "Filters": {
        "comparableTypeID": 1,
        "contractTypeID": 1,
        "categoryTypeID": null,
        "propertyTypeID": null,
        "propertyQualityID": null,
        "boundingBox": null,
        "marketZoneID": "10242",
        "omiZoneID": null,
        "municipalityID": null,
        "minRooms": null,
        "maxRooms": null,
        "minBathrooms": null,
        "maxBathrooms": null,
        "elevator": null,
        "garage": null,
        "maintenanceStatusID": null,
        "pubblicationStatusID": [
            1,
            2
        ],
        "minGrossSquareFootage": null,
        "maxGrossSquareFootage": null,
        "unitFloor": null,
        "minPrice": null,
        "maxPrice": null,
        "clientTypeID": null,
        "phoneNumberProvided": null
    },
    "Pagination": {
        "page": 1,
        "limit": 10
    },
    "Sorting": {
        "by": "date",
        "direction": "desc"
    }
}'

Example Response

{
    "_metadata": {
        "limit": 10,
        "page": 1,
        "pages": {
            "first": 1,
            "last": 13,
            "next": 2,
            "previous": null,
            "self": 1
        },
        "query": {
            "comparableType": "Offerta",
            "contractType": "Vendita",
            "marketZoneID": "10242",
            "pubblicationStatus": [
                "Nuovo",
                "Pubblicato"
            ],
            "sorting": {
                "by": "date",
                "direction": "desc"
            }
        },
        "total_count": 127,
        "request_id": "4de30278-24d8-48e1-8c40-3bcc57fe2514",
        "map": "http://sandbox-comparables.realitycs.it/map/4de30278-24d8-48e1-8c40-3bcc57fe2514"
    },
    "items": [
        {
            "_metadata": [
                "comparabili_maintenancestatus_?",
                "comparabili_comparabletype_1",
                "comparabili_propertytype_1"
            ],
            "address": "Via Broletto",
            "askingPrice": 130000,
            "askingPricePsm": 1238,
            "balconycount": null,
            "box_auto": null,
            "comparableType": "Offerta",
            "coverImage": null,
            "dataOwnership": "test",
            "distance": null,
            "distanceFromPoi": null,
            "elevator": null,
            "energyClass": null,
            "garden_type": null,
            "grossSquareFootage": 105,
            "grossSquareFootageDelta": null,
            "heatingsystem": null,
            "maintenanceStatus": "",
            "municipalityID": 15146,
            "numberOfBathrooms": null,
            "numberOfBuildingFloor": null,
            "price": null,
            "pricePsm": null,
            "projUuid": null,
            "propertyType": "Appartamento",
            "rooms": 5,
            "salesDate": null,
            "showCases": null,
            "similarityRanking": null,
            "unitFloor": null,
            "uri": "/comparable/009c5188-f907-4bbb-9743-934e811cade0",
            "uuid": "009c5188-f907-4bbb-9743-934e811cade0",
            "value": null,
            "valuePsm": null
        },
        {
            "_metadata": [
                "comparabili_maintenancestatus_2",
                "comparabili_comparabletype_1",
                "comparabili_propertytype_1"
            ],
            "address": "Via Cusani",
            "askingPrice": 8000000,
            "askingPricePsm": 21622,
            "balconycount": null,
            "box_auto": null,
            "comparableType": "Offerta",
            "coverImage": "https://images.realitycs.it/img/125132603/1829631669",
            "dataOwnership": "test",
            "distance": null,
            "distanceFromPoi": null,
            "elevator": true,
            "energyClass": "C",
            "garden_type": null,
            "grossSquareFootage": 370,
            "grossSquareFootageDelta": null,
            "heatingsystem": null,
            "maintenanceStatus": "Ottimo / Ristrutturato",
            "municipalityID": 15146,
            "numberOfBathrooms": 4,
            "numberOfBuildingFloor": 3,
            "price": null,
            "pricePsm": null,
            "projUuid": null,
            "propertyType": "Appartamento",
            "rooms": 6,
            "salesDate": null,
            "showCases": null,
            "similarityRanking": null,
            "unitFloor": null,
            "uri": "/comparable/1455fdb3-db2e-43e5-8771-0b8ff9e33b40",
            "uuid": "1455fdb3-db2e-43e5-8771-0b8ff9e33b40",
            "value": null,
            "valuePsm": null
        },
        ...
        {
            "_metadata": [
                "comparabili_maintenancestatus_?",
                "comparabili_comparabletype_1",
                "comparabili_propertytype_99"
            ],
            "address": "Via Rastrelli",
            "askingPrice": 50000,
            "askingPricePsm": 625,
            "balconycount": null,
            "box_auto": null,
            "comparableType": "Offerta",
            "coverImage": "https://images.realitycs.it/img/124850169/1822836437",
            "dataOwnership": "test",
            "distance": null,
            "distanceFromPoi": null,
            "elevator": null,
            "energyClass": "Non classificabile",
            "garden_type": null,
            "grossSquareFootage": 80,
            "grossSquareFootageDelta": null,
            "heatingsystem": null,
            "maintenanceStatus": "",
            "municipalityID": 15146,
            "numberOfBathrooms": 1,
            "numberOfBuildingFloor": 1,
            "price": null,
            "pricePsm": null,
            "projUuid": null,
            "propertyType": "Altro",
            "rooms": 1,
            "salesDate": null,
            "showCases": null,
            "similarityRanking": null,
            "unitFloor": null,
            "uri": "/comparable/cfb0b401-d693-4098-95d5-a3c798b7d76b",
            "uuid": "cfb0b401-d693-4098-95d5-a3c798b7d76b",
            "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 if projects are requested (propertyTypeID 112)

Request fields

Field	Required	Type	Example	Notes
`marketZoneID`	**	string	`10242`
`municipalityID`	**	string	`15146`
`omiZoneID`	**	string	`A074B1`
`boundingBox`	**	geojson	`{"type": "Polygon","coordinates": [...]}`
`comparableTypeID`	*	int	`1`
`contractTypeID`	*	int	`1`	depends on comparableTypeID
`propertyTypeID`		int	`4`
`categoryTypeID`		int	`2`
`propertyQualityID`		int	`3`
`minGrossSquareFootage`		int	`50`
`maxGrossSquareFootage`		int	`120`
`minRooms`		int	`1`
`maxRooms`		int	`2`
`minPrice`		int	`1200000`
`maxPrice`		int	`2500000`
`minBathrooms`		int	`1`
`maxBathrooms`		int	`3`
`maintenanceStatusID`		int	`2`
`pubblicationStatusID`		int	`4`
`unitFloor`		float	`1`
`elevator`		bool	`true`
`garage`		bool	`false`
`minDate`		string	`12/01/2025`
`maxDate`		string	`25/09/2025`
`clientTypeID`		int	`2`
`phoneNumberProvided`		bool	`false`
`lat`		float	`'45.4775832'`	relative to a POI, used to calculate distance
`lng`		float	`'9.1858904'`	relative to a POI, used to calculate distance
`minDeletionDate`		string	`12/01/2025`
`maxDeletionDate`		string	`25/09/2025`
`minModifiedDate`		string	`12/01/2025`
`maxModifiedDate`		string	`25/09/2025`
`energyClassID`		int	`15`
`minConstructionYear`		string	`1950`
`maxConstructionYear`		string	`2025`
`duplicatesFilterID`		int	`2`
`projectCategoryID`	**	int	`2`
`groupProject`	**	bool	`true`	if true it groups all projects in a single project item if present
`minProjectEndDate`		string	`12/01/2025`	only for projects
`maxProjectEndDate`		string	`25/09/2025`	only for projects
`minProjectStartDate`		string	`12/01/2025`	only for projects
`maxProjectStartDate`		string	`25/09/2025`	only for projects
`minProjResidentialUnits`		int	`5`	only for projects
`maxProjResidentialUnits`		int	`8`	only for projects
`minProjCommercialUnits`		int	`2`	only for projects
`maxProjCommercialUnits`		int	`10`	only for projects
`minPricePsm`		int	`2000`
`maxPricePsm`		int	`5000`
`occupancyStatusFree`		bool	`true`
`minNumberOfBuildingFloor`		int	`1`
`maxNumberOfBuildingFloor`		int	`4`
`minShowcases`		int	`2`
`maxShowcases`		int	`5`
`chimneyFlue`		bool	`false`
`fumeAspiration`		bool	`true`
`reception`		bool	`true`
`minShedHeight`		float	`1.5`
`maxShedHeight`		float	`2.9`
`broadbandInternet`		bool	`true`
`disabledPeopleAccess`		bool	`false`
`securityAlarm`		bool	`true`
`minGarageDoorWidth`		float	`3.5`
`maxGarageDoorWidth`		float	`5`

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 `date`, `price`, `pricepsm`, `lastmodified`, `removed`, `energyclass` or `distance` relative to a POI
direction	desc	str	List the results by ascending (asc) or descending (desc) order