---
title: "Search comparables (v1)"
method: POST
path: "/api/v1/comparables/search"
tags: ["api---comparables"]
---

# Search comparables (v1)

`POST /api/v1/comparables/search`

## Request

- Base URL: `https://api.casafari.com`
- URL: `https://api.casafari.com/api/v1/comparables/search`
- Auth: HTTP bearer

Returns comparable properties by the given parameters.

## Request body

- ApiSearchComparablesRequestV1
  - `comparables_count` integer, required: Maximum number of comparable properties in results.
  - `coordinates` object: 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>
    - `latitude` number, required: Latitude.
    - `longitude` number, required: Longitude.
  - `target_point` object: 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>
    - `coordinates` object: Target point coordinates to search around.
      - `latitude` number, required: Latitude.
      - `longitude` number, required: Longitude.
    - `address` string: Address of the property to define the point to search around.
    - `cadastral_reference` object: Cadastral reference of the property to define the point to search around. <br/>For now available only for Spain.
      - `country_code` 'ES', required: Country code following the ISO 3166-1 alpha-2 rules.
      - `cadastral_reference` string, required: Cadastral reference of the estate.
      - `province` string: Name of the estate's province.
      - `municipality` string: Name of the estate's municipality.
  - `distance` number: 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>
  - `location_boundary` object, required: 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.
    - `polygon` object[]: Closed polygon of geo-points to search within. First and last points must match.
      - `latitude` number, required: Latitude.
      - `longitude` number, required: Longitude.
    - `circle` object: Circle boundary to search within.
      - `distance` number: Maximum distance in kilometers from the requested `target_point` to the properties.
      - `target_point` object, required: Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided.
        - `coordinates` object: Target point coordinates to search around.
          - `latitude` number, required: Latitude.
          - `longitude` number, required: Longitude.
        - `address` string: Address of the property to define the point to search around.
        - `cadastral_reference` object: Cadastral reference of the property to define the point to search around. <br/>For now available only for Spain.
          - `country_code` 'ES', required: Country code following the ISO 3166-1 alpha-2 rules.
          - `cadastral_reference` string, required: Cadastral reference of the estate.
          - `province` string: Name of the estate's province.
          - `municipality` string: Name of the estate's municipality.
  - `sold_or_rented_after` string, date, nullable: 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` 'sale' | 'rent', required: Operation type.
  - `business_type` 'sale' | 'rent': 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` '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': 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` string[], required: <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> penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex<br/><strong>house:</strong> townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (<span style="color:red">DEPRECATED</span>), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house<br/><strong>room:</strong> room<br/><strong>building:</strong> office_building, apartment_building, mix_use_building<br/><strong>investment:</strong> retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt<br/><strong>plot:</strong> rural_plot, urban_plot, plot (<span style="color:red">DEPRECATED</span>)<br/><strong>other:</strong> garage, other, 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` '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': 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` integer: The minimum price filter for comparables result.
  - `max_price` integer: The maximum price filter for comparables result.
  - `condition` 'used' | 'ruin' | 'very-good' | 'new' | 'other': Property condition, as returned by the [GET /api/v1/references/conditions](/#operation/api__get__v1__references__conditions) endpoint.
  - `bedrooms` integer: Number of bedrooms (cannot be used together with `rooms`).
  - `rooms` integer: Number of rooms (cannot be used together with `bedrooms`).
  - `bathrooms` integer: Number of bathrooms.
  - `construction_year` integer: Desired construction year.
  - `total_area` integer: 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` integer: 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` 'no_floor' | 'ground' | 'middle' | 'top': 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` string[]: List of floor types.
  - `floor_number` integer[]: Desired list of floor numbers. Negative values indicate underground floors (e.g. basements).<br>Minimum value is -250.<br>Maximum value is 250.
  - `orientation` 'exterior' | 'interior': Property view orientation.
  - `view` 'water' | 'landscape' | 'city' | 'golf' | 'park': 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` string[]: List of views from the property.
  - `direction` 'north' | 'south' | 'east' | 'west': 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` string[]: List of cardinal directions the property faces.
  - `characteristics` object: Property characteristics.
    - `must_have` string[]: Include only properties that have all these characteristics.
    - `nice_to_have` string[]: Include properties that have any of these characteristics.
    - `exclude` string[]: Exclude properties that contain any of these characteristics.
  - `energy_certificate` 'Unknown' | 'A+' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H': 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` string[]: 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` string[]: List of energy ratings.
  - `days_on_market_from` integer: Minimum days on market value.
  - `days_on_market_to` integer: Maximum days on market value.
  - `with_agencies` string[]: 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` string[]: 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` boolean: Exclude properties that are significantly underpriced or overpriced compared to similar properties.

## Response `200`

- ApiSearchComparablesResponseV1
  - `results` object[], required: Array of found comparable properties.
    - `property_id` integer, required: ID of the property.
    - `property_url` string, nullable: URL of the property in the CASAFARI website.
    - `primary_listing_id` integer, required: Primary listing (ad) ID of the property which is defined after the matching into property.
    - `type` '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', required: Property type, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.
    - `type_group` 'apartment' | 'house' | 'investment' | 'plot' | 'other', required: Property type group, as returned by the [GET /api/v1/references/types](/#operation/api__get__v1__references__types) endpoint.
    - `coordinates` object, nullable, required: Property coordinates.
      - `latitude` number, required: Latitude.
      - `longitude` number, required: Longitude.
    - `location` object, required: Information about property location.
      - `location_id` integer, required: ('Location ID, as returned by the [POST /api/v1/references/locations](/#operation/api__post__v1__references__locations) endpoint.',)
      - `name` string, required: Location name.
      - `administrative_level` string, required: Location administrative level.
      - `zip_codes` string[]: The location zip codes.
    - `locations_structure` object[], required: Information about all the parent locations (including property location) up to the country.
      - `location_id` integer, required: ('Location ID, as returned by the [POST /api/v1/references/locations](/#operation/api__post__v1__references__locations) endpoint.',)
      - `name` string, required: Location name.
      - `administrative_level` string, required: Location administrative level.
      - `zip_codes` string[]: The location zip codes.
    - `address` string, required: Property address.
    - `zip_code` string, nullable, required: The location zip code.
    - `distance` number, nullable: Distance in kilometers from target point to the property. Not calculated for search by polygon.
    - `construction_year` integer, required: Construction year.
    - `total_area` integer, required: Total area.
    - `living_area` integer, required: Living area.
    - `plot_area` integer, required: Plot area.
    - `terrace_area` integer, required: Terrace area.
    - `bedrooms` integer, nullable, required: Number of bedrooms.
    - `rooms` integer, required: Number of rooms.
    - `bathrooms` integer, required: Number of bathrooms.
    - `floor_number` integer, nullable, required: Exact floor number. Negative values indicate underground floors (e.g. basements).
    - `condition` 'used' | 'ruin' | 'very-good' | 'new' | 'other', required: Property condition, as returned by the [GET /api/v1/references/conditions](/#operation/api__get__v1__references__conditions) endpoint.
    - `features` object, required: Property features, as returned by the [GET /api/v1/references/features](/#operation/api__get__v1__references__features) endpoint.
      - `floor` 'no_floor' | 'ground' | 'middle' | 'top', nullable, required: Floor type.
      - `orientation` 'exterior' | 'interior', nullable, required: Property view orientation.
      - `view` 'water' | 'landscape' | 'city' | 'golf' | 'park', nullable, required: 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` string[], nullable, required: List of views from the property.
      - `direction` 'north' | 'south' | 'east' | 'west', nullable, required: 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` string[], nullable, required: List of cardinal directions the property faces.
      - `characteristics` string[], nullable, required: Property characteristics.
    - `operations` string[], required: Operation types for which property is available.
    - `sale_status` 'active' | 'reserved' | 'hold' | 'sold' | 'none', required: Sale status.
    - `sale_currency` string, required: Sale price currency code.
    - `sale_price` integer, required: Sale price, in the currency of the listings (specified by the `sale_currency` field).
    - `sale_price_base` integer, required: Sale price, in Euros.
    - `sale_price_per_sqm` number, required: Sale price per square meter, in the currency of the listings (specified by the `sale_currency` field).
    - `sale_price_per_sqm_base` number, required: ('Sale price per square meter, in Euros.',)
    - `rent_status` 'active' | 'reserved' | 'hold' | 'rented' | 'none', required: Rent status.
    - `rent_currency` string, required: Rent price currency code.
    - `rent_price` integer, required: Rent price, in the currency of the listings (specified by the `rent_currency` field).
    - `rent_price_base` integer, required: Rent price, in Euros.
    - `rent_price_per_sqm` number, required: Rent price per square meter, in the currency of the listings (specified by the `rent_currency` field).
    - `rent_price_per_sqm_base` number, required: ('Rent price per square meter, in Euros.',)
    - `rent_period` 'day' | 'week' | 'fortnight' | 'month' | 'year' | 'none', required: Rent period.
    - `title` string, required: Property title.
    - `description` string, required: Property description.
    - `thumbnails` string[]: List of the thumbnail image URLs.
    - `pictures` string[]: List of the original picture image URLs.
    - `gross_yield` number, required: Gross yield in percentage.
    - `sold_at` string, date, nullable, required: Date when the property was sold.
    - `rented_at` string, date, nullable, required: Date when the property was rented.
    - `total_sale_price_change` number, required: Total sale price change in percents.
    - `total_rent_price_change` number, required: Total rent price change in percents.
    - `last_sale_price_reduction` number, required: Last sale price reduction in percents.
    - `last_rent_price_reduction` number, required: Last rent price reduction in percents.
    - `sale_price_last_change` object, nullable, required: Information about the last change of sale price.
      - `change_date` string, date, required: Date of the change.
      - `old_value` integer, required: Value before change.
      - `new_value` integer, required: Value after change.
    - `rent_price_last_change` object, nullable, required: Information about the last change of rent price.
      - `change_date` string, date, required: Date of the change.
      - `old_value` integer, required: Value before change.
      - `new_value` integer, required: Value after change.
    - `sale_time_on_market` object, nullable: Information about the property last activity on the sales market.
    - `rent_time_on_market` object, nullable: Information about the property last activity on the rental market.
    - `sale_active_listings_count` integer: Number of active listings for this property on the sales market.
    - `rent_active_listings_count` integer: Number of active listings for this property on the rental market.
    - `similarity_score` number: Similarity score of the property. Value between 0 and 1. Indicates how property parameters are close to the requested ones.
    - `listing_urls` string[], required: Listing urls of the comparable.
    - `is_dvf` boolean: Whether the property taken from DVF.
    - `is_outlier` boolean: Whether the property is considered an outlier based on its price.
    - `is_private_property` boolean, required: Whether the property is listed by a private individual, as opposed to an agent or a professional.
    - `energy_certificate` string: Energy certificate classification that attests to the energy efficiency of a property. <br/><strong>This field is deprecated and will be removed in the next major update.</strong><br/><strong>Please, use `energy_rating` field instead.</strong>
    - `energy_rating` string: Energy rating that attests to the energy efficiency of a property.
  - `statistics` object, nullable, required: Statistics information for the found comparables (for `operation` defined in the request).
    - `average_price` integer, required: Average price.
    - `average_price_per_sqm` number, required: Average price per square meter.
    - `average_time_on_the_market` integer, required: Average number of days on the market.
    - `average_listings_per_property` number, required: Average number of listings per property.
    - `sold_or_rented_in_last_six_months` integer, required: Number of properties that were sold or rented during the last 6 months in the requested location.
  - `estimated_prices` object, nullable, required: Estimated prices calculated based on the found comparables (for `operation` defined in the request).
    - `fast_sell_price` integer, required: Fast sell price.
    - `fair_market_price` integer, required: Fair market price.
    - `out_of_market_price` integer, required: Out of market price.
    - `fast_sell_price_per_sqm` number, required: Fast sell price per square meter.
    - `fair_market_price_per_sqm` number, required: Fair market price per square meter.
    - `out_of_market_price_per_sqm` number, required: Out of market price per square meter.
  - `casafari_link` string, uri, nullable, required: Link to Comparative Market Analysis page.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/casafari/apis/casafari-api.md) · [All operations](https://skmtc.dev/casafari/apis/casafari-api/llms.txt) · [OpenAPI document](https://skmtc.dev/casafari/apis/casafari-api/revisions/6743b99d4bf9?raw)