# How do I build a monthly local market report with Casafari data?

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

Build a monthly local market report from Casafari Area Insights by running a fixed sequence of calls on one boundary. Use `ma_get_time_series_data` and `ma_get_time_series_operations` for price trends and activity, the price, bedroom and time-on-market distributions for structure, and `ma_get_heatmap` for districts. An AI assistant can run it from one prompt; a script can schedule it.

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

## Short answer

A complete local market report is the same set of Area Insights calls, made on one boundary, for one type group and one operation, every reporting period.

There are two ways to run it:

- An AI assistant connected to the Casafari MCP server can run the whole sequence from a single prompt.
- A script can make the same calls on a schedule and fill a template.

Each report section maps to specific tools.

## Steps

### Resolve the area and the reporting period

1. Call `list_servers` the first time, to read the Area Insights instructions.
2. Call `ma_get_location_typeahead` with an English place name and keep the `location_id`.
3. Call `ma_get_current_datetime` and derive the reporting window, for example the last full month or quarter, as `date_range`.

### Prices: avg_price_psqm series and delta_pct, yoy_last, cagr

4. Call `ma_get_time_series_data` with `data_point` `avg_price_psqm` and `date_interval` `month`.
5. Call `ma_get_time_series_operations` on the same segment with `operations` `["delta_pct", "yoy_last", "cagr"]`.

### Activity: new, sold_or_rented, available_on_market, price_down series

6. Call `ma_get_time_series_data` four times with identical filters, once each for `new`, `sold_or_rented`, `available_on_market` and `price_down`.

### Structure: price, bedrooms and time-on-market distributions

7. Call `ma_get_price_distribution`, `ma_get_bedrooms_distribution` and `ma_get_time_on_market_distribution` on the same boundary.

### Geography: heatmap by district

8. Call `ma_get_heatmap` with the city's `location_id` and `data_point` `avg_price_psqm`. Repeat with `new` or `price_down` if useful.

### Narrative: POST /market-analytics-api/analysis over REST

9. If you also use REST, send `POST /market-analytics-api/analysis` with the same `custom_location_boundary`, `business_type` and `types`, and add its market analysis to the report. Its response fields are documented on the [operation page](/docs/rest/area-insights/analysis).

## Example prompt and output

Prompt to the assistant: *"Write a Q3 market report for apartments for sale in Lisbon. Cover price per m² by month with the change over the quarter and year on year, new supply against sales, price cuts, prices by bedrooms, days on market by price band, and a district comparison."*

The assistant runs steps 1 to 8 and returns a report skeleton like this, filled with the live values:

```text
Lisbon apartments for sale: Q3 market report
Source: Casafari Area Insights. Counts are properties, not advertisements.

1. Prices: average price per m² by month; change over the quarter (delta_pct),
   year on year (yoy_last), compound growth (cagr)
2. Activity: new properties, properties sold or rented, properties on the market,
   price cuts, by month
3. Structure: properties per price band (mean band marked); average price and
   price per m² by bedrooms; days on market by price band
4. Geography: districts ranked by average price per m²
5. What it means for buyers and sellers
```

The recipe above makes 13 MCP calls, plus one optional REST call. These docs publish no market figures; every number in the report comes from the calls.

## How to read the result

### Quote properties, not advertisements

Casafari's property graph merges every advertisement of a property into one record. Say "properties" in every count, for example "new properties this month", so readers do not mistake the figures for advertisement counts from a portal.

### State the type group and operation in every chart

Every figure belongs to one `type_group` (`apartment` or `house`) and one `business_type` (`sale` or `rent`). Label each chart with both, and with the boundary and the period. Also say whether `exclude_outliers` was on; it is on by default.

## Limits

Availability:

- Every Area Insights tool and REST operation used here is available to Casafari clients with their Casafari account.
- Self-serve access for new users is coming soon.
- `ma_get_time_series_operations` and `ma_get_heatmap` exist over MCP only.

Coverage:

- The tool descriptions name no specific market.

Scheduling:

- These docs describe no built-in scheduler or report template. Your assistant, script or agent runs the calls.
- Machine-readable references for building one are listed in [For AI agents](/docs/agents).

### Apartment and house groups only

The Area Insights MCP tools accept `type_group` `apartment` or `house` only. A report on offices, retail or plots cannot be built from these tools.

### Several calls per report; each product has a quota and no quota figures are published

A full report takes 13 MCP calls, and each product has a quota. When the quota is used up, tools answer `Request limit reached for this product.` and retrying will not help. The sources publish no quota or price figures; ask [Casafari](https://www.casafari.com/). See [rate limits and quotas](/docs/faq/rate-limits-and-quotas).

## Questions

### Can I schedule the report to run every month?

Yes, but the scheduling is yours. These docs describe no built-in scheduler. Run a script on your own scheduler that makes the same calls each month. An unattended agent can sign in to the Casafari MCP server with client credentials that Casafari issues for the account. A REST script signs in with `POST /login` or an API client created by the account owner.

### Can the report cover rentals and sales together?

Yes, as two parallel sections. Every Area Insights request takes one `business_type`, `sale` or `rent`, so run the price, activity and distribution calls once for each and present them side by side. Comparing the two sets, for example the average sale price per m² against asking rent per m² in the same boundary, gives readers a rental-yield context.

### Can I include my own agency's share of the market?

Not from Area Insights: its tools take no agency filter. In Germany, AgentGraph AI's `agentgraph_territory_map` with `client_brand` returns your own network's share per district, alongside the shares held by franchise networks and independents. `agentgraph_area_benchmark` shows how the market splits between broker types. These docs describe no market-share operation for other countries.

### Can I export the data to a BI tool?

Yes. Every Area Insights tool returns structured JSON, such as `date_start` and `value` rows or distribution bands, which a script can write to any BI tool. Developers can use the REST API at https://api.casafari.com, described in https://docs.api.casafari.com/openapi.json, or the MCP tool schemas in /tools.json. Bulk delivery is described under Data Export at /docs/data-export.

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