# How long will a property take to sell or rent in this area?

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

Casafari Area Insights shows how long properties stay on the market in an area, by price band. `ma_get_time_on_market_distribution` returns, for each band, the average `days_on_market` and `months_on_market` plus `properties_count`, for sale or for rent. To check one home, `comps_get-comparables` from Comparables & Valuation adds `average_time_on_the_market` for its comparables.

Products: [Area Insights](/docs/area-insights), [Comparables & Valuation](/docs/comparables-valuation).

## Short answer

`ma_get_time_on_market_distribution` groups properties into price bands. For each band it returns:

- `lower_bound` and `upper_bound` (the price limits).
- The average `days_on_market` and `months_on_market`.
- `properties_count` (the number of properties in the band).

The bands with the shortest time on market show where properties move fastest. For a single home, `comps_get-comparables` returns `statistics.average_time_on_the_market` for its comparable set.

## Steps

### Resolve the area

1. Call `ma_get_location_typeahead` with an English place name, for example `Porto`, and keep the `location_id`. Call `ma_get_current_datetime` if you need "the last 12 months" as concrete dates.

### Call ma_get_time_on_market_distribution with type_group, business_type, price_range and date_range (start of the last active period)

2. Call `ma_get_time_on_market_distribution` with a `request_data` object.
   - Required: `type_group` (`apartment` or `house`), `business_type` (`sale` or `rent`) and `custom_location_boundary` (`location_ids` or a `circle`).
   - Optional: `price_range` to set the overall price window, and `date_range`, which filters properties by the start date of their last active period on the market.
   - Other filters: `bedrooms_range`, `total_area_range`, `construction_year_range`, `conditions` and `exclude_outliers` (default `true`).

### Cross-check one property with comps_get-comparables: statistics.average_time_on_the_market and days_on_market_from/to filters

3. Call `comps_get-comparables` around the home.
   - Required: `comparables_count` (1 to 50), `location_boundary` (a circle with a `target_point` and `distance` in km, or a polygon), `operation` and `comparables_types`.
   - Read `statistics.average_time_on_the_market` (average days on market).
   - Use `days_on_market_from` and `days_on_market_to` (1 to 10,000) to narrow the set.

## Example: apartments for sale in Porto in the last year

Prompt to the assistant: *"At what price do apartments for sale in Porto sell fastest? Use properties whose last active period started in the last 12 months."*

The assistant calls `ma_get_location_typeahead` (`Porto`), then `ma_get_current_datetime`, then `ma_get_time_on_market_distribution`:

```json
{
  "request_data": {
    "type_group": "apartment",
    "business_type": "sale",
    "custom_location_boundary": {"location_ids": [PORTO_LOCATION_ID]},
    "date_range": {"min": "YYYY-MM-DD"},
    "exclude_outliers": true
  }
}
```

The response has this shape:

```json
{"result": [{"lower_bound": <int>, "upper_bound": <int or null>, "days_on_market": <int>, "months_on_market": <number>, "properties_count": <int>}]}
```

To check a specific 2-bedroom apartment, the assistant then calls `comps_get-comparables`:

```json
{
  "comparables_count": 20,
  "location_boundary": {"circle": {"target_point": {"address": "Avenida dos Aliados, Porto"}, "distance": 1}},
  "operation": "sale",
  "comparables_types": ["apartment"],
  "bedrooms": 2
}
```

It reports which price band has the lowest `days_on_market`, and where the home's `estimated_prices.fair_market_price` falls among the bands. The figures come from the live calls; these docs publish none.

## How to read the result

### Bands with low days_on_market and high properties_count are liquid

A band with few days on market and many properties is a liquid segment: buyers are active and there is enough evidence to trust the average. A band with few properties gives a less reliable average. An open `upper_bound` (null) marks the top band.

### Use the result to set a price that sells within your client's deadline

If the client must sell within a set number of months:

1. Find the bands whose `months_on_market` fits that deadline.
2. Compare them with the comparables' `estimated_prices`: `fast_sell_price`, `fair_market_price` and `out_of_market_price`.
3. Pricing near `fast_sell_price` inside a liquid band supports a quick sale. Pricing near `out_of_market_price` invites a long wait and later cuts.

## Limits

Availability:

- `ma_get_time_on_market_distribution` and `comps_get-comparables` are available to Casafari clients with MCP access, using their Casafari account.
- Self-serve access for new users is coming soon.
- The REST equivalent `POST /market-analytics-api/distributions/time-on-market` ([page](/docs/rest/area-insights/time-on-market-distribution)) is for Casafari client accounts.

Coverage and data:

- In `comps_get-comparables`, the cadastral-reference target point is Spain only. Elsewhere, use an address or coordinates.
- The Area Insights tool descriptions name no specific market.
- The docs do not publish the exact formula behind days on market.

Pricing and quotas:

- The sources give no figures for pricing or quotas. Ask [Casafari](https://www.casafari.com/).

### Apartment and house groups only

`type_group` in the distribution accepts only `apartment` or `house`. For other property types, `comps_get-comparables` accepts a wider list of `comparables_types`, one type group per request.

### date_range filters by the start of the last active period, not by sale date

`date_range` selects properties whose last active period on the market started within the range. It does not select by the date a property was sold or rented. So recent periods include properties still on the market.

## Questions

### Can I see time on market for rentals?

Yes. Set `business_type` to `rent` in `ma_get_time_on_market_distribution` and the bands show how long rental properties stay on the market at each rent level. For a single rental home, call `comps_get-comparables` with `operation` `rent` and read `statistics.average_time_on_the_market`. Each request covers either sale or rent, so landlords and sellers run separate calls.

### Can I restrict to 3-bedroom properties or a construction year range?

Yes. In `ma_get_time_on_market_distribution`, set `bedrooms_range` to `{"min": 3, "max": 3}` and `construction_year_range` to the years you want, for example a `min` and `max`. You can add `total_area_range`, `conditions` or `characteristics` too. Narrow filters leave fewer properties per band, so check `properties_count` before trusting an average.

### How does Casafari measure days on market when several agencies advertise the same property?

Casafari merges every advertisement of a property into one record, with its full history of appearances, removals, price changes and status changes, all dated. Time on market is therefore measured per property, not per advertisement. The docs do not publish the exact calculation, for example how gaps between active periods are handled. The distribution's `date_range` refers to the last active period.

### Can I filter comparables by days on market?

Yes. `comps_get-comparables` accepts `days_on_market_from` and `days_on_market_to`, each from 1 to 10,000 days. Use them to compare a home with properties that sat on the market for a similar time, or to exclude stale stock. The response's `statistics.average_time_on_the_market` gives the average days on market of the comparables found.

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