Understand an area · Use case

How have asking prices per m² moved in an area over time?

Casafari Area Insights builds a price-per-m² trend for a city or district over MCP. ma_get_time_series_data with data_point avg_price_psqm returns one value per week, month, quarter or year. ma_get_time_series_operations then computes growth and volatility on that series, such as delta_pct, cagr, yoy_last and cv. Resolve the place first with ma_get_location_typeahead.

Products: Area Insights

#Short answer

Area Insights returns one aggregated value per period for the metric you pick. For a price trend, set data_point to avg_price_psqm and date_interval to week, month, quarter or year. ma_get_time_series_data then returns a list of date_start and value pairs.

A second tool, ma_get_time_series_operations, takes the same filters as one segment and computes statistics on that series. The statistics include:

• delta_pct: percentage change between the first and last data points.
• cagr: compound annual growth rate.
• cv: coefficient of variation.
• std: standard deviation.
• Others such as yoy_last, median, slope_per_period and moving averages like movavg_last_12.

Set business_type to rent to get asking rents per m² instead of sale prices.

If your assistant has not used Area Insights before, it should call list_servers first. That call returns the group's own usage instructions.

#Steps

#Resolve the place with ma_get_location_typeahead (English name) to a location_id

1. Call ma_get_location_typeahead with location_name set to an English place name, for example Valencia. Each suggestion has location_id, name, matched_name, administrative_level and breadcrumbs (the parent locations). If several places share the name, add more detail to the query and use the breadcrumbs to pick the right one. See How do I turn a place name into a location id?.

#Anchor the date range with ma_get_current_datetime

2. Call ma_get_current_datetime; it takes no input. It returns current_datetime in ISO format, so "the last three years" becomes a concrete date_range.min.

#Call ma_get_time_series_data: type_group, business_type, data_point avg_price_psqm, date_interval, date_range

3. Call ma_get_time_series_data with one request_data object.
   • Required: type_group (apartment or house), business_type (sale or rent), alias (your name for the segment), custom_location_boundary (location_ids or a circle), data_point (avg_price_psqm), date_interval and date_range (min is required, max is optional).
   • Optional filters: price_range, price_per_sqm_range, bedrooms_range, bathrooms_range, total_area_range, construction_year_range, characteristics, conditions and exclude_outliers.

#Call ma_get_time_series_operations with operations such as delta_pct, cagr, yoy_last, cv, movavg_last_12

4. Call ma_get_time_series_operations.
   • Set request_data.segment to the same object you sent in step 3.
   • Set request_data.operations to the statistics you want. If you omit operations, a default minimal set is applied.
   • The result has alias, date_start, date_end, date_interval, total_of_data_points and results, a list of operation and value pairs.

#Example: apartments for sale in Valencia, quarterly

Prompt to the assistant: "Chart the average price per m² of apartments for sale in Valencia by quarter since 2022, then give me the total change, the CAGR and how volatile it was."

The assistant calls list_servers, then ma_get_location_typeahead (Valencia), then ma_get_current_datetime, then ma_get_time_series_data:

{
  "request_data": {
    "alias": "Valencia apartments, sale",
    "type_group": "apartment",
    "business_type": "sale",
    "custom_location_boundary": {"location_ids": [LOCATION_ID]},
    "data_point": "avg_price_psqm",
    "date_interval": "quarter",
    "date_range": {"min": "2022-01-01"}
  }
}

LOCATION_ID is the location_id the typeahead returned for Valencia. The response has one row per quarter, in this shape:

{"result": [{"date_start": "YYYY-MM-DD", "value": <number or null>}]}

Next, the assistant calls ma_get_time_series_operations. It sends the same object as segment, with "operations": ["delta_pct", "cagr", "yoy_last", "cv", "movavg_last_12"]. The response has this shape:

{"alias": "Valencia apartments, sale", "date_start": "...", "date_end": "...", "date_interval": "quarter", "total_of_data_points": <n>, "results": [{"operation": "delta_pct", "value": <number>}, {"operation": "cagr", "value": <number>}]}

The assistant charts the quarterly values. It reports delta_pct as the total change since 2022, cagr as the yearly pace and cv as the volatility. The figures come from the live call; these docs publish none.

#How to read the result

#date_start marks the period; dates snap to Monday and Sunday

date_start is the first day of each period for the date_interval you chose.

The tool adjusts the dates you send:

• If date_range.min is not a Monday, the closest previous Monday is used.
• If date_range.max is not a Sunday, the closest previous Sunday is used.

So the first and last periods can start or end a few days away from the dates you typed.

#Prefer avg_price_psqm over avg_price for broad comparisons

The tool's own notes recommend price per m² over total price for broader analyses. Price per m² keeps differences in home size from distorting the comparison between areas. Use avg_price when you need the typical ticket size in one area.

#exclude_outliers is on by default

exclude_outliers defaults to true. It removes properties that are significantly underpriced or overpriced compared with similar properties. Leave it on for trend work. Set it to false only if you want extreme values included.

#Limits

Availability:

• Every step on this page is available to Casafari clients with MCP access, using their Casafari account.
• Self-serve access for new users is coming soon.
• The REST equivalent of the series, POST /market-analytics-api/time-series (page), is for Casafari client accounts.
• ma_get_time_series_operations exists over MCP only.

Coverage and data:

• The Area Insights tool descriptions name no specific market. See per-tool coverage.
• Values aggregate prices of properties in Casafari's property graph. They show where asking prices moved, not registry sale prices.

Pricing, quotas and refresh:

• The sources give no figures for pricing, quotas or data refresh frequency. Ask Casafari.
• When a product's quota is used up, its tools answer Request limit reached for this product.

#Up to 10 location ids or one circle of 50 to 50,000 m per request

custom_location_boundary takes either location_ids (1 to 10 ids) or a circle.

• A circle has a target_point (latitude and longitude) and a distance in metres, from 50 to 50,000.
• Polygons are not accepted by Area Insights over MCP.
• Several ids in one request form one boundary and return a single series.

#One type group per request; send separate requests to compare apartments and houses

type_group is either apartment or house. To compare the two, send one request per type group with otherwise identical filters, as the tool's notes advise.

#Questions

All use cases