{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/casafari/main/json-schema/casafari-api-search-comparables-request-v1-schema.json",
  "title": "ApiSearchComparablesRequestV1",
  "x-generated": "2026-10-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/casafari-api-openapi.json#/components/schemas/ApiSearchComparablesRequestV1",
  "properties": {
    "comparables_count": {
      "type": "integer",
      "maximum": 50.0,
      "minimum": 1.0,
      "description": "Maximum number of comparable properties in results."
    },
    "coordinates": {
      "properties": {
        "latitude": {
          "type": "number",
          "maximum": 90.0,
          "minimum": -90.0,
          "description": "Latitude."
        },
        "longitude": {
          "type": "number",
          "maximum": 180.0,
          "minimum": -180.0,
          "description": "Longitude."
        }
      },
      "type": "object",
      "required": [
        "latitude",
        "longitude"
      ],
      "description": "Target point coordinates to search around. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `target_point.coordinates` field instead.</strong>"
    },
    "target_point": {
      "properties": {
        "coordinates": {
          "properties": {
            "latitude": {
              "type": "number",
              "maximum": 90.0,
              "minimum": -90.0,
              "description": "Latitude."
            },
            "longitude": {
              "type": "number",
              "maximum": 180.0,
              "minimum": -180.0,
              "description": "Longitude."
            }
          },
          "type": "object",
          "required": [
            "latitude",
            "longitude"
          ],
          "description": "Target point coordinates to search around."
        },
        "address": {
          "type": "string",
          "description": "Address of the property to define the point to search around."
        },
        "cadastral_reference": {
          "properties": {
            "country_code": {
              "type": "string",
              "enum": [
                "ES"
              ],
              "description": "Country code following the ISO 3166-1 alpha-2 rules.",
              "writeOnly": true
            },
            "cadastral_reference": {
              "type": "string",
              "description": "Cadastral reference of the estate.",
              "writeOnly": true
            },
            "province": {
              "type": "string",
              "description": "Name of the estate's province.",
              "writeOnly": true
            },
            "municipality": {
              "type": "string",
              "description": "Name of the estate's municipality.",
              "writeOnly": true
            }
          },
          "type": "object",
          "required": [
            "country_code",
            "cadastral_reference"
          ],
          "description": "Cadastral reference of the property to define the point to search around. <br/>For now available only for Spain."
        }
      },
      "type": "object",
      "description": "Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `location_boundary.circle` field instead.</strong>"
    },
    "distance": {
      "type": "number",
      "maximum": 50.0,
      "minimum": 0.05,
      "description": "Maximum distance in kilometers from the requested `target_point` to comparable properties.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `location_boundary.circle` field instead.</strong>",
      "default": 5
    },
    "location_boundary": {
      "properties": {
        "polygon": {
          "items": {
            "properties": {
              "latitude": {
                "type": "number",
                "maximum": 90.0,
                "minimum": -90.0,
                "description": "Latitude."
              },
              "longitude": {
                "type": "number",
                "maximum": 180.0,
                "minimum": -180.0,
                "description": "Longitude."
              }
            },
            "type": "object",
            "required": [
              "latitude",
              "longitude"
            ]
          },
          "type": "array",
          "minItems": 4,
          "description": "Closed polygon of geo-points to search within. First and last points must match. "
        },
        "circle": {
          "properties": {
            "distance": {
              "type": "number",
              "maximum": 50.0,
              "minimum": 0.05,
              "description": "Maximum distance in kilometers from the requested `target_point` to the properties.",
              "default": 5
            },
            "target_point": {
              "properties": {
                "coordinates": {
                  "properties": {
                    "latitude": {
                      "type": "number",
                      "maximum": 90.0,
                      "minimum": -90.0,
                      "description": "Latitude."
                    },
                    "longitude": {
                      "type": "number",
                      "maximum": 180.0,
                      "minimum": -180.0,
                      "description": "Longitude."
                    }
                  },
                  "type": "object",
                  "required": [
                    "latitude",
                    "longitude"
                  ],
                  "description": "Target point coordinates to search around."
                },
                "address": {
                  "type": "string",
                  "description": "Address of the property to define the point to search around."
                },
                "cadastral_reference": {
                  "properties": {
                    "country_code": {
                      "type": "string",
                      "enum": [
                        "ES"
                      ],
                      "description": "Country code following the ISO 3166-1 alpha-2 rules.",
                      "writeOnly": true
                    },
                    "cadastral_reference": {
                      "type": "string",
                      "description": "Cadastral reference of the estate.",
                      "writeOnly": true
                    },
                    "province": {
                      "type": "string",
                      "description": "Name of the estate's province.",
                      "writeOnly": true
                    },
                    "municipality": {
                      "type": "string",
                      "description": "Name of the estate's municipality.",
                      "writeOnly": true
                    }
                  },
                  "type": "object",
                  "required": [
                    "country_code",
                    "cadastral_reference"
                  ],
                  "description": "Cadastral reference of the property to define the point to search around. <br/>For now available only for Spain."
                }
              },
              "type": "object",
              "description": "Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided."
            }
          },
          "type": "object",
          "required": [
            "target_point"
          ],
          "description": "Circle boundary to search within."
        }
      },
      "type": "object",
      "description": "Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided."
    },
    "sold_or_rented_after": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered."
    },
    "operation": {
      "type": "string",
      "enum": [
        "sale",
        "rent"
      ],
      "description": "Operation type."
    },
    "business_type": {
      "type": "string",
      "enum": [
        "sale",
        "rent"
      ],
      "description": "Operation type.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `operation` field instead.</strong>"
    },
    "comparables_type": {
      "type": "string",
      "enum": [
        "apartment",
        "studio",
        "duplex",
        "penthouse",
        "dachgeschosswohnung",
        "etagenwohnung",
        "erdgeschosswohnung",
        "country_house",
        "house",
        "palace",
        "townhouse",
        "villa",
        "country_estate",
        "chalet",
        "bungalow",
        "family_house",
        "reihenhaus",
        "reihenendhaus",
        "reihenmittelhaus",
        "einfamilienhaus",
        "zweifamilienhaus",
        "landwirtschaftliche_betriebe",
        "retail",
        "office",
        "industrial",
        "warehouse",
        "hotel",
        "other_commercial",
        "restaurant",
        "werkstatt",
        "plot",
        "urban_plot",
        "rural_plot",
        "room",
        "other",
        "garage",
        "parking",
        "apartment_building",
        "office_building",
        "mix_use_building"
      ],
      "description": "Comparables property type, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `comparables_types` field instead.</strong>"
    },
    "comparables_types": {
      "items": {
        "type": "string",
        "enum": [
          "apartment",
          "studio",
          "duplex",
          "penthouse",
          "dachgeschosswohnung",
          "etagenwohnung",
          "erdgeschosswohnung",
          "country_house",
          "house",
          "palace",
          "townhouse",
          "villa",
          "country_estate",
          "chalet",
          "bungalow",
          "family_house",
          "reihenhaus",
          "reihenendhaus",
          "reihenmittelhaus",
          "einfamilienhaus",
          "zweifamilienhaus",
          "landwirtschaftliche_betriebe",
          "retail",
          "office",
          "industrial",
          "warehouse",
          "hotel",
          "other_commercial",
          "restaurant",
          "werkstatt",
          "plot",
          "urban_plot",
          "rural_plot",
          "room",
          "other",
          "garage",
          "parking",
          "apartment_building",
          "office_building",
          "mix_use_building"
        ]
      },
      "type": "array",
      "description": "<br>Country availability per type is available at the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.<br><br>Property types by type groups:<br/><strong>apartment:</strong> erdgeschosswohnung, penthouse, duplex, etagenwohnung, apartment, dachgeschosswohnung, studio<br/><strong>house:</strong> zweifamilienhaus, palace, reihenmittelhaus, landwirtschaftliche_betriebe, chalet, house, reihenendhaus, townhouse, einfamilienhaus, bungalow, villa, reihenhaus, family_house (<span style=\"color:red\">DEPRECATED</span>), country_estate, country_house<br/><strong>room:</strong> room<br/><strong>building:</strong> office_building, mix_use_building, apartment_building<br/><strong>investment:</strong> other_commercial, warehouse, industrial, office, hotel, restaurant, werkstatt, retail<br/><strong>plot:</strong> urban_plot, rural_plot, plot (<span style=\"color:red\">DEPRECATED</span>)<br/><strong>other:</strong> other, garage, parking<br/><br/><i><span style=\"color:red\">Note that you can select multiple types only from one property type group.</span></i>"
    },
    "property_type": {
      "type": "string",
      "enum": [
        "apartment",
        "studio",
        "duplex",
        "penthouse",
        "dachgeschosswohnung",
        "etagenwohnung",
        "erdgeschosswohnung",
        "country_house",
        "house",
        "palace",
        "townhouse",
        "villa",
        "country_estate",
        "chalet",
        "bungalow",
        "family_house",
        "reihenhaus",
        "reihenendhaus",
        "reihenmittelhaus",
        "einfamilienhaus",
        "zweifamilienhaus",
        "landwirtschaftliche_betriebe",
        "retail",
        "office",
        "industrial",
        "warehouse",
        "hotel",
        "other_commercial",
        "restaurant",
        "werkstatt",
        "plot",
        "urban_plot",
        "rural_plot",
        "room",
        "other",
        "garage",
        "parking",
        "apartment_building",
        "office_building",
        "mix_use_building"
      ],
      "description": "Comparables property type, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.<br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `comparables_types` field instead.</strong>"
    },
    "min_price": {
      "type": "integer",
      "maximum": 2147483647.0,
      "minimum": 0.0,
      "description": "The minimum price filter for comparables result.",
      "default": 0
    },
    "max_price": {
      "type": "integer",
      "maximum": 2147483647.0,
      "minimum": 1.0,
      "description": "The maximum price filter for comparables result."
    },
    "condition": {
      "type": "string",
      "enum": [
        "used",
        "ruin",
        "very-good",
        "new",
        "other"
      ],
      "description": "Property condition, as returned by the [GET /api/v1/references/conditions](/#operation/api__get__v1__references__conditions) endpoint."
    },
    "bedrooms": {
      "type": "integer",
      "maximum": 15000.0,
      "minimum": 0.0,
      "description": "Number of bedrooms (cannot be used together with `rooms`)."
    },
    "rooms": {
      "type": "integer",
      "maximum": 15000.0,
      "minimum": 0.0,
      "description": "Number of rooms (cannot be used together with `bedrooms`)."
    },
    "bathrooms": {
      "type": "integer",
      "maximum": 15000.0,
      "minimum": 1.0,
      "description": "Number of bathrooms."
    },
    "construction_year": {
      "type": "integer",
      "maximum": 3000.0,
      "minimum": 1.0,
      "description": "Desired construction year."
    },
    "total_area": {
      "type": "integer",
      "maximum": 10000000.0,
      "minimum": 5.0,
      "description": "Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided."
    },
    "plot_area": {
      "type": "integer",
      "maximum": 10000000.0,
      "minimum": 20.0,
      "description": "Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided."
    },
    "floor": {
      "type": "string",
      "enum": [
        "no_floor",
        "ground",
        "middle",
        "top"
      ],
      "description": "Floor type. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `floors` field instead.</strong>"
    },
    "floors": {
      "items": {
        "type": "string",
        "enum": [
          "no_floor",
          "ground",
          "middle",
          "top"
        ]
      },
      "type": "array",
      "description": "List of floor types."
    },
    "floor_number": {
      "items": {
        "type": "integer",
        "maximum": 250.0,
        "minimum": -250.0
      },
      "type": "array",
      "description": "Desired list of floor numbers. Negative values indicate underground floors (e.g. basements).<br>Minimum value is -250.<br>Maximum value is 250."
    },
    "orientation": {
      "type": "string",
      "enum": [
        "exterior",
        "interior"
      ],
      "description": "Property view orientation."
    },
    "view": {
      "type": "string",
      "enum": [
        "water",
        "landscape",
        "city",
        "golf",
        "park"
      ],
      "description": "View from the property. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `views` field instead.</strong>"
    },
    "views": {
      "items": {
        "type": "string",
        "enum": [
          "water",
          "landscape",
          "city",
          "golf",
          "park"
        ]
      },
      "type": "array",
      "description": "List of views from the property."
    },
    "direction": {
      "type": "string",
      "enum": [
        "north",
        "south",
        "east",
        "west"
      ],
      "description": "Cardinal direction the property faces. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `directions` field instead.</strong>"
    },
    "directions": {
      "items": {
        "type": "string",
        "enum": [
          "north",
          "south",
          "east",
          "west"
        ]
      },
      "type": "array",
      "description": "List of cardinal directions the property faces."
    },
    "characteristics": {
      "properties": {
        "must_have": {
          "items": {
            "type": "string",
            "enum": [
              "balcony",
              "elevator",
              "no_elevator",
              "garage",
              "garden",
              "parking",
              "storage",
              "swimming_pool",
              "terrace",
              "rental_license",
              "furniture",
              "rented_out",
              "life_annuity"
            ]
          },
          "type": "array",
          "description": "Include only properties that have all these characteristics."
        },
        "nice_to_have": {
          "items": {
            "type": "string",
            "enum": [
              "balcony",
              "elevator",
              "no_elevator",
              "garage",
              "garden",
              "parking",
              "storage",
              "swimming_pool",
              "terrace",
              "rental_license",
              "furniture",
              "rented_out",
              "life_annuity"
            ]
          },
          "type": "array",
          "description": "Include properties that have any of these characteristics."
        },
        "exclude": {
          "items": {
            "type": "string",
            "enum": [
              "balcony",
              "elevator",
              "no_elevator",
              "garage",
              "garden",
              "parking",
              "storage",
              "swimming_pool",
              "terrace",
              "rental_license",
              "furniture",
              "rented_out",
              "life_annuity"
            ]
          },
          "type": "array",
          "description": "Exclude properties that contain any of these characteristics."
        }
      },
      "type": "object",
      "description": "Property characteristics."
    },
    "energy_certificate": {
      "type": "string",
      "enum": [
        "Unknown",
        "A+",
        "A",
        "B",
        "C",
        "D",
        "E",
        "F",
        "G",
        "H"
      ],
      "description": "Energy certificate. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `energy_ratings` field instead.</strong>"
    },
    "energy_certificates": {
      "items": {
        "type": "string",
        "enum": [
          "Unknown",
          "A+",
          "A",
          "B",
          "C",
          "D",
          "E",
          "F",
          "G",
          "H"
        ]
      },
      "type": "array",
      "description": "List of energy certificates. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `energy_ratings` field instead.</strong>"
    },
    "energy_ratings": {
      "items": {
        "type": "string",
        "enum": [
          "Unknown",
          "A+",
          "A",
          "B",
          "C",
          "D",
          "E",
          "F",
          "G",
          "H"
        ]
      },
      "type": "array",
      "description": "List of energy ratings."
    },
    "days_on_market_from": {
      "type": "integer",
      "maximum": 10000.0,
      "minimum": 1.0,
      "description": "Minimum days on market value."
    },
    "days_on_market_to": {
      "type": "integer",
      "maximum": 10000.0,
      "minimum": 1.0,
      "description": "Maximum days on market value."
    },
    "with_agencies": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "description": "Return properties from specified agencies, companies or sources. To find allowed agency names use the [GET /api/v1/references/agencies](/#operation/api__get__v1__references__agencies) endpoint."
    },
    "without_agencies": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "description": "Exclude properties from specified agencies, companies or sources. To find allowed agency names use the [GET /api/v1/references/agencies](/#operation/api__get__v1__references__agencies) endpoint."
    },
    "exclude_outliers": {
      "type": "boolean",
      "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties.",
      "default": true
    }
  },
  "type": "object",
  "required": [
    "comparables_count",
    "location_boundary",
    "operation",
    "comparables_types"
  ]
}