# Search estimated prices (v1)

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

`POST https://api.casafari.com/api/v1/valuation/comparables-prices`

[Comparables & Valuation](/docs/comparables-valuation) · [REST API](/docs/rest/comparables-valuation). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token).

Over MCP: [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) (related). See [MCP and REST compared](/docs/parity#comparables-valuation).

## Description

Returns estimated prices by the given parameters.

## Request body

Content type `application/json`. Optional. Type: `object`.

- `comparables_count` (integer, required): Maximum number of comparable properties in results. 1–50.
- `target_point` (object, optional): Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.**
  - `coordinates` (object, optional): Target point coordinates to search around.
    - `latitude` (number, required): Latitude. -90–90.
    - `longitude` (number, required): Longitude. -180–180.
  - `address` (string, optional): Address of the property to define the point to search around.
  - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain.
    - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`.
    - `cadastral_reference` (string, required): Cadastral reference of the estate.
    - `province` (string, optional): Name of the estate's province.
    - `municipality` (string, optional): Name of the estate's municipality.
- `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to comparable properties. **This field is deprecated and will be removed in the next major update.** **Please, use `location_boundary.circle` field instead.** 0.05–50; default 5.
- `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[], optional): Closed polygon of geo-points to search within. First and last points must match. at least 4 items.
    - `latitude` (number, required): Latitude. -90–90.
    - `longitude` (number, required): Longitude. -180–180.
  - `circle` (object, optional): Circle boundary to search within.
    - `distance` (number, optional): Maximum distance in kilometers from the requested `target_point` to the properties. 0.05–50; default 5.
    - `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, optional): Target point coordinates to search around.
        - `latitude` (number, required): Latitude. -90–90.
        - `longitude` (number, required): Longitude. -180–180.
      - `address` (string, optional): Address of the property to define the point to search around.
      - `cadastral_reference` (object, optional): Cadastral reference of the property to define the point to search around. For now available only for Spain.
        - `country_code` (string, required): Country code following the ISO 3166-1 alpha-2 rules. Values: `ES`.
        - `cadastral_reference` (string, required): Cadastral reference of the estate.
        - `province` (string, optional): Name of the estate's province.
        - `municipality` (string, optional): Name of the estate's municipality.
- `sold_or_rented_after` (string (date), optional, 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` (string, required): Operation type. Values: `sale`, `rent`.
- `comparables_type` (string, optional): Comparables property type, as returned by the GET /api/v1/references/types endpoint. **This field is deprecated and will be removed in the next major update.** **Please, use `comparables_types` field instead.** Values: `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_types` (string[], required): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking *Note that you can select multiple types only from one property type group.* Values: `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`.
- `min_price` (integer, optional): The minimum price filter for comparables result. 0–2147483647; default 0.
- `max_price` (integer, optional): The maximum price filter for comparables result. 1–2147483647.
- `condition` (string, optional): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`.
- `bedrooms` (integer, optional): Number of bedrooms (cannot be used together with `rooms`). 0–15000.
- `rooms` (integer, optional): Number of rooms (cannot be used together with `bedrooms`). 0–15000.
- `bathrooms` (integer, optional): Number of bathrooms. 1–15000.
- `construction_year` (integer, optional): Desired construction year. 1–3000.
- `total_area` (integer, optional): 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. 5–10000000.
- `plot_area` (integer, optional): 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. 20–10000000.
- `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`.
- `floor_number` (integer[], optional): Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250. -250–250.
- `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`.
- `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`.
- `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`.
- `characteristics` (object, optional): Property characteristics.
  - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
  - `nice_to_have` (string[], optional): Include properties that have any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
  - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
- `energy_certificate` (string, optional): Energy certificate. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`.
- `energy_certificates` (string[], optional): List of energy certificates. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_ratings` field instead.** Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`.
- `energy_ratings` (string[], optional): List of energy ratings. Values: `Unknown`, `A+`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`.
- `days_on_market_from` (integer, optional): Minimum days on market value. 1–10000.
- `days_on_market_to` (integer, optional): Maximum days on market value. 1–10000.
- `with_agencies` (string[], optional): Return properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint.
- `without_agencies` (string[], optional): Exclude properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint.
- `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true.

## Example request

Placeholders only: replace the token and the values with your own.

```bash
curl -X POST "https://api.casafari.com/api/v1/valuation/comparables-prices" \
  -H "Authorization: Bearer $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "comparables_count": 20,
  "location_boundary": {
    "circle": {
      "distance": 3.5,
      "target_point": {
        "coordinates": {
          "latitude": 38.74,
          "longitude": -9.17
        }
      }
    }
  },
  "sold_or_rented_after": "2020-06-01",
  "days_on_market_from": 10,
  "days_on_market_to": 1000,
  "operation": "sale",
  "comparables_types": [
    "apartment"
  ],
  "bedrooms": 2,
  "construction_year": 2010,
  "total_area": 125,
  "condition": "used",
  "floors": [
    "middle",
    "top"
  ],
  "floor_number": [
    3,
    5
  ],
  "views": [
    "city",
    "landscape"
  ],
  "directions": [
    "west",
    "north"
  ],
  "characteristics": {
    "must_have": [
      "balcony",
      "elevator"
    ],
    "nice_to_have": [
      "garage",
      "parking",
      "storage"
    ]
  },
  "energy_ratings": [
    "A",
    "B",
    "C"
  ]
}'
```

## Responses

### 200 OK

Type: `object`.

- `statistics` (object, 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, 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.

Example from the API description:

```json
{
  "statistics": {
    "average_price": 767950,
    "average_price_per_sqm": 6376,
    "average_time_on_the_market": 169,
    "average_listings_per_property": 6.2,
    "sold_or_rented_in_last_six_months": 453
  },
  "estimated_prices": {
    "fast_sell_price": 741210,
    "fair_market_price": 797000,
    "out_of_market_price": 852790,
    "fast_sell_price_per_sqm": 5929.68,
    "fair_market_price_per_sqm": 6376,
    "out_of_market_price_per_sqm": 6822.32
  }
}
```

### 400 Bad Request

Type: `object`.

- `errors` (object, optional): Description of the errors encountered.

### 401 Unauthorized

Type: `object`.

- `detail` (string, optional): Description of the error encountered.

### 403 Forbidden

Type: `object`.

- `detail` (string, optional): Description of the error encountered.

## Questions about this

- [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation)
- [How do I value a home or find comparables with Casafari MCP?](/docs/faq/example-valuation)