# How do I value a property with comparables?

> **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).

To value a property with comparables, call the Casafari MCP server's `comps_get-comparables` tool from Comparables & Valuation with a circle or polygon, an operation (sale or rent) and property types. One call returns up to 50 ranked comparable properties, aggregated market statistics, registry records where they exist and three estimated prices: fast-sell, fair market and out-of-market.

Products: [Comparables & Valuation](/docs/comparables-valuation).

## Short answer

One call to `comps_get-comparables` with a `location_boundary` (a circle around coordinates or an address, or a closed polygon), an `operation` and `comparables_types` returns comparable properties ranked by relevance, aggregated `statistics` and three `estimated_prices`. The same response carries `casafari_link`, which opens the Comparative Market Analysis page, and a `valuation_id`.

## Steps

### Call `list_servers` and read the Comparables & Valuation instructions

1. Call [`list_servers`](/docs/gateway/list_servers). It returns each product your account can use, with that product's own instructions. If the `comps` group is missing, your subscription does not cover it, and retrying will not help.

### Define the target: coordinates or an address, a radius in km, operation sale, one type group

2. Set `location_boundary.circle.target_point` to exactly one of `coordinates` (`latitude`, `longitude`), `address`, or `cadastral_reference` (Spain only).
3. Set `location_boundary.circle.distance` in kilometres, from 0.05 to 50 (default 5).
4. Set `operation` to `sale` (or `rent` for a rental valuation).
5. Set `comparables_types` to one or more types from a single group, for example `["apartment"]`.

### Add filters: bedrooms or rooms, bathrooms, total_area, condition, characteristics, energy_ratings

6. Describe the subject property. Use `bedrooms` or `rooms` (never both), `bathrooms`, `total_area` in square metres, `condition` (`used`, `ruin`, `very-good`, `new`, `other`), `characteristics` with `must_have`, `nice_to_have` and `exclude` lists (such as `terrace`, `elevator`, `parking`), and `energy_ratings` (`A+` to `H`, or `Unknown`). Optional extras include `construction_year`, `floors`, `floor_number`, `views`, `orientation`, `directions`, `min_price`, `max_price`, `days_on_market_from` and `days_on_market_to`.

### Call `comps_get-comparables` with `comparables_count` up to 50

7. Call [`comps_get-comparables`](/docs/comparables-valuation/get-comparables) with its four required inputs: `comparables_count` (1 to 50), `location_boundary`, `operation` and `comparables_types`, plus your filters.

## Example: a 3-bedroom flat near Avenida da Liberdade, Lisbon

### The request

A person asks their AI assistant: *"What is a 3-bedroom flat near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km."* The assistant calls `list_servers`, then `comps_get-comparables` with:

```json
{
  "comparables_count": 20,
  "location_boundary": {
    "circle": {
      "target_point": { "address": "Avenida da Liberdade, Lisbon" },
      "distance": 1
    }
  },
  "operation": "sale",
  "comparables_types": ["apartment"],
  "bedrooms": 3
}
```

### The response

The answer has this shape (values omitted; they depend on the market on the day you call):

```json
{
  "results": [
    {
      "property_id": "...",
      "property_url": "...",
      "similarity_score": "...",
      "distance": "...",
      "sale_status": "...",
      "sale_price": "...",
      "sale_currency": "...",
      "sale_price_per_sqm": "...",
      "sale_price_last_change": { "change_date": "...", "old_value": "...", "new_value": "..." },
      "is_outlier": "..."
    }
  ],
  "statistics": { "average_price": "...", "average_price_per_sqm": "...", "average_time_on_the_market": "...", "sold_or_rented_in_last_six_months": "..." },
  "estimated_prices": { "fast_sell_price": "...", "fair_market_price": "...", "out_of_market_price": "...", "fair_market_price_per_sqm": "..." },
  "dvf_results": [],
  "transactional_data": [],
  "casafari_link": "...",
  "valuation_id": "..."
}
```

The assistant then answers with a value range and the comparables behind it.

## How to read the result

### `estimated_prices`: `fair_market_price`, `fast_sell_price`, `out_of_market_price`

`fair_market_price` is the central estimate, `fast_sell_price` the quick-sale price and `out_of_market_price` the premium end. Each has a per-m² version (`fair_market_price_per_sqm` and so on). Quote the range from fast-sell to out-of-market with the fair market price as the anchor. The estimates are computed from the comparables found, for the `operation` in the request.

### `statistics`: `average_price_per_sqm`, `average_time_on_the_market`, `sold_or_rented_in_last_six_months`

`average_price_per_sqm` lets you check the estimate against the micro-market. `average_time_on_the_market` is the average number of days on the market: a long figure argues for pricing nearer the fast-sell estimate. `sold_or_rented_in_last_six_months` counts properties sold or rented in the requested location over the last 6 months; a low number means thin evidence.

### `results`: `similarity_score`, `distance`, `is_outlier`, `sale_price_last_change`

Each result is one property in the [property graph](/docs/property-graph), merged from every advertisement of it, so you [count properties, not advertisements](/docs/faq/count-properties-not-advertisements). `similarity_score` (0 to 1) says how close its parameters are to the ones you asked for. `distance` is kilometres from the target point (not calculated for a polygon). `is_outlier` flags a price out of line with similar properties. `sale_price_last_change` gives the date and the old and new values of the last price change, and `sale_status` and `sold_at` show whether the property is active, reserved or sold.

### `dvf_results` and `transactional_data`: official registry records

`dvf_results` holds DVF records (official property transfer records) with `sale_price`, `sale_price_psqm`, `sold_at` and `total_area`. `transactional_data` holds notarial records with `price`, `price_per_sqm`, `sold_at` and `cadastral_reference`. Either can be empty or absent where no records match. Use them as independent evidence next to the advertised prices.

Finally, `casafari_link` opens the Comparative Market Analysis page for this valuation. More on the product: [Comparables & Valuation](/docs/comparables-valuation) and [What does Comparables & Valuation do?](/docs/faq/what-is-comparables-valuation).

## Limits

`comps_get-comparables` is available to Casafari clients with MCP access, using their Casafari account; self-serve access for new users is coming soon. The REST operations `POST /api/v2/comparables/search` and `POST /api/v1/valuation/comparables-prices` are for Casafari client accounts: see the [Comparables & Valuation REST API](/docs/rest/comparables-valuation). Prices, quotas and rate limits are not published in these docs; ask [Casafari](https://www.casafari.com/). When a product's quota is used up, its tools answer `Request limit reached for this product.`

### Radius 0.05 to 50 km; 0.5 to 1 km in cities, 2 to 5 km in rural areas

`distance` accepts 0.05 to 50 km and defaults to 5. The tool's own advice is a tight radius of 0.5 to 1 km in urban areas and 2 to 5 km in rural ones, so comparables reflect the same micro-market.

### Types from one group per request

The groups are apartment, house, room, building, investment, plot and other. You can select several types only from one group.

### sold_or_rented_after defaults to 9 months ago; null means active properties only

Set an earlier `YYYY-MM-DD` date to include older sales or rentals, or pass `null` to consider only properties currently on the market.

### exclude_outliers is true by default

Significantly underpriced or overpriced properties are left out unless you set `exclude_outliers` to `false`. The estimate reflects only the comparables and records found; apart from the Spain-only cadastral reference input, the tool's description names no per-market coverage.

## Questions

### Can I value a rental instead of a sale?

Yes, set `operation` to `rent` in `comps_get-comparables` to value a rental. The tool then matches rental comparables, and `statistics` and `estimated_prices` refer to the rent operation. Check each comparable's `rent_period` (day, week, fortnight, month or year) before comparing figures, and add Area Insights' `ma_get_time_series_data` with `business_type: rent` to see how rents have moved.

### What is the difference between fair market, fast-sell and out-of-market price?

They are three price points computed from the comparables found. `fair_market_price` is the fair market value, `fast_sell_price` is the quick-sale price for a faster sale, and `out_of_market_price` is the premium end, which the tool's description calls premium pricing. Each comes with a per-m² version. Casafari's documentation does not publish the formula behind them.

### Can I exclude my own agency's properties from the comparables?

Yes, put your agency's name in `without_agencies` to exclude properties from specified agencies, companies or sources; `with_agencies` does the opposite. Allowed agency names come from the REST operation `GET /api/v1/references/agencies`, which is for Casafari client accounts. Excluding your own stock keeps the valuation independent of the asking prices you set yourself.

### Why does the tool return fewer comparables than I asked for?

`comparables_count` is a maximum, not a guarantee. The tool returns only properties inside your circle or polygon that match the operation, types and filters, and it excludes outliers by default. To get more, widen `distance`, relax filters such as `bedrooms` or `characteristics`, move `sold_or_rented_after` earlier, or set `exclude_outliers` to false.

### Can I pass a polygon instead of a circle?

Yes, set `location_boundary.polygon` to a closed list of at least 4 geo-points (`latitude`, `longitude`) whose first and last points match. Give either a polygon or a circle, not both. With a polygon, the `distance` field in the results is not calculated, so rank the comparables by `similarity_score` instead.

All use cases: [Use cases](/docs/use-cases#valuation).