# Is it a buyer's or a seller's market 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 whether an area favours buyers or sellers through activity time series. Run `ma_get_time_series_data` once each for `new`, `sold_or_rented`, `available_on_market`, `price_up` and `price_down` on the same area and filters. New supply outpacing sales, with more cuts than rises, points to a buyer's market; the reverse points to a seller's market.

Products: [Area Insights](/docs/area-insights).

## Short answer

Area Insights offers five activity data points:

- `new`: newly advertised properties.
- `sold_or_rented`: properties sold or rented.
- `available_on_market`: properties on the market.
- `price_up`: price increases.
- `price_down`: price decreases.

All five come from the status and price changes recorded in Casafari's [property graph](/docs/property-graph). Each property record keeps every price change, status change, appearance and removal, with dates. Read the five series together to judge whether stock is building or being absorbed, and whether sellers are cutting or raising prices.

## Steps

### Resolve the area and anchor dates

1. Call `ma_get_location_typeahead` with an English place name, for example `Barcelona`, and keep the `location_id`.
2. Call `ma_get_current_datetime` to turn "the last two years" into a concrete `date_range`.

### Run ma_get_time_series_data once per data_point with identical filters

3. Call `ma_get_time_series_data` five times. Keep `type_group`, `business_type`, `custom_location_boundary`, `date_interval`, `date_range` and every filter identical, and change only `data_point`. The tool's own notes recommend reusing the same filters with different `data_point` values, for example to compare new supply with sold properties.

### Compute trend_strength, slope_per_period and delta_pct with ma_get_time_series_operations

4. For each series, call `ma_get_time_series_operations` with the same object as `segment`. Set `operations` to `["trend_strength", "slope_per_period", "delta_pct"]`. You can add `inc_steps` and `dec_steps` to count rising and falling periods.

### Map where cuts concentrate with ma_get_heatmap and data_point price_down

5. Call `ma_get_heatmap` with the city's `location_id` and `data_point` `price_down`. It returns one value per district, so you can see where cuts concentrate.

### Over REST, POST /market-analytics-api/analysis for a market analysis of the same boundary

6. Send `POST /market-analytics-api/analysis` with the same `custom_location_boundary`, plus `business_type`, `types` and any range filters. The response fields are documented on the [operation page](/docs/rest/area-insights/analysis); this page does not repeat them.

## Example: apartments for sale in Barcelona, monthly

Prompt to the assistant: *"Is the Barcelona apartment market cooling? Compare new supply with sales and price cuts with price rises, month by month since 2024."*

The assistant calls `ma_get_location_typeahead` (`Barcelona`), then `ma_get_current_datetime`, then four series requests. The four requests are identical except for `data_point`:

```json
{
  "request_data": {
    "alias": "Barcelona apartments, sale",
    "type_group": "apartment",
    "business_type": "sale",
    "custom_location_boundary": {"location_ids": [BARCELONA_LOCATION_ID]},
    "data_point": "new",
    "date_interval": "month",
    "date_range": {"min": "2024-01-01"}
  }
}
```

It then lines the series up by `date_start`:

| Pair | Series A | Series B | What the gap shows |
|---|---|---|---|
| Supply vs absorption | `new` | `sold_or_rented` | Whether stock is building or being absorbed |
| Price pressure | `price_down` | `price_up` | Whether sellers are adjusting downwards |

Finally it adds `available_on_market` as the stock line and `delta_pct` for each series. The figures come from the live calls; these docs publish none.

## How to read the result

### New supply rising faster than sold_or_rented: stock builds

When `new` runs above `sold_or_rented` month after month, and `available_on_market` climbs, supply is outpacing absorption. That favours buyers and supports harder negotiation. The opposite pattern, with falling stock, favours sellers.

### price_down outnumbering price_up: sellers adjusting

A rising count of `price_down` against `price_up` shows asking prices meeting resistance. Check where it happens with the `price_down` heatmap before generalising to the whole city.

### Counts are properties, not advertisements

The property graph merges every advertisement of the same property into one record. So a home advertised by three agencies counts once in `new`, `available_on_market` and the other counts. See [Why Casafari counts properties](/docs/faq/count-properties-not-advertisements).

## Limits

Availability:

- All Area Insights MCP tools, plus the REST operations `POST /market-analytics-api/time-series` and `POST /market-analytics-api/analysis`, are available to Casafari clients with their Casafari account.
- Self-serve access for new users is coming soon.

Coverage and data:

- The tool descriptions name no specific market.
- Activity counts come from advertised properties and their status changes. They are not registry or notarial records.

Pricing, quotas and refresh:

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

### One data_point per request

Each `ma_get_time_series_data` or `ma_get_time_series_operations` request carries a single `data_point`, `type_group` and `business_type`. A five-signal view therefore takes five series requests, plus one operations request per series.

### REST analysis body fields are the ones published on its operation page

The `POST /market-analytics-api/analysis` request body accepts these fields:

- `custom_location_boundary`, `business_type`, `types`.
- `conditions`, `energy_ratings`, `orientations`, `views`, `directions`, `floors`, `characteristics`.
- `price_range`, `rooms_range`, `bedrooms_range`, `bathrooms_range`, `total_area_range`, `plot_area_range`, `construction_year_range`.

Its response is described only on the operation page.

## Questions

### What does sold_or_rented count exactly?

`sold_or_rented` counts the properties sold or rented in each period, as the tool description puts it. The count comes from status changes to sold or rented recorded in Casafari's property graph, and each property counts once. It is not registry or notarial data. The docs publish no further detail on how a status change is confirmed, so treat the count as activity in advertised properties.

### Can I separate sales from rentals?

Yes. Every Area Insights time series request takes `business_type`, either `sale` or `rent`. With `sale`, the series describe the sales market; with `rent`, they describe the rental market. Each request covers one of the two, so run the same set of data points twice to compare the markets. Keep every other filter identical so the two views stay comparable.

### Can I filter to new-build or very-good condition?

Yes, by property condition. Set `conditions` to `["new"]` or `["very-good"]`. The allowed values are `used`, `ruin`, `very-good`, `new` and `other`, as returned by `GET /api/v1/references/conditions`. Note that this is a condition filter, not a new-development flag. The Area Insights time series schema has no separate new-development field.

### How is a property counted if several agencies advertise it?

Once. Casafari deduplicates advertisements from agency websites and portals and merges them into one record per property, with its full price and status history. Area Insights counts those property records, so a home advertised by several agencies adds one to `new`, `available_on_market` or `price_down`, not one per advertisement. See /docs/faq/count-properties-not-advertisements.

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