# `ma_get_time_series_operations`

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

Get Time Series Operations. Product: [Area Insights](/docs/area-insights). Annotations: Read-only.

Call it as `ma_get_time_series_operations` on `https://mcp.casafari.com/` (the backend's own name is `get_time_series_operations`).

Over REST: no operation in the public API description does this. [MCP and REST compared](/docs/parity#area-insights).

## Description

Performs analytical **time-series operations** (e.g., `mean`, `delta_pct`, `CAGR`, `cv`, `std`, etc.)
for a **single geographic or analytical segment** using real-estate historical data.

This tool enables focused analysis of **real estate market dynamics** over time —
such as prices, listings, or sales — within one defined location or subset.

#### Purpose
Designed for analytical scenarios such as:
- Tracking how property prices evolve in a specific area.
- Measuring growth trends (e.g., CAGR, percentage deltas).
- Evaluating volatility using standard deviation or coefficient of variation.
- Studying local market activity over a given period.

#### Input (`request_data`)
Expects an instance of `MCPTimeSeriesOperationsRequestSchema`, which includes:
- **`segment`** → a single `MCPTimeSeriesRequestSchema` object defining the geographic or analytical subset.
- **`operations`** → list of time-series operations (`TimeSeriesOperationEnum`) to compute.

`MCPTimeSeriesRequestSchema` includes:
- `custom_location_boundary`: spatial boundary (circle or list of location IDs).
- `data_point`: metric to analyze (e.g. `AVERAGE_PRICE_PER_SQM`, `SOLD_COUNT`, `NEW_LISTED_COUNT`).
- `date_interval`: aggregation interval (`WEEK`, `MONTH`, `QUARTER`, or `YEAR`).
- `date_range`: start and end of the analysis period.
- Optional property filters (price, area, rooms, construction year, etc.).
- `exclude_outliers`: whether to exclude statistical outliers.

> **Analytical consistency rule:**
The analytical context (data_point, date_interval, business_type, etc.) must remain
consistent within the request. The `segment` may only redefine `custom_location_boundary`
and `alias` relative to the base filter.

#### Operations
Supported operations from `TimeSeriesOperationEnum` include:
- `mean` — average value across the time range.
- `delta_pct` — percentage change between the first and last data points.
- `cagr` — compound annual growth rate.
- `std` — standard deviation.
- `cv` — coefficient of variation.
- (plus others defined in the enum).

#### LLM Behavior
- On success → returns a **single analytical result** (`MCPTimeSeriesUnitResponseSchema`)
  containing computed metrics for the requested segment.
- On error → raises a `ToolError` with an error message.

#### Example Success Response
```json
    {
      "alias": "Madrid Center",
      "date_start": "2020-01-01",
      "date_end": "2024-01-01",
      "date_interval": "MONTH",
      "total_of_data_points": 48,
      "results": [
        {"operation": "mean", "value": 3200.5},
        {"operation": "delta_pct", "value": 12.4},
        {"operation": "cagr", "value": 0.032}
      ]
    }
```

#### Example Error Response
```
ToolError: No data found for the specified segment.
```

#### Example Use Cases
- Analyze **average price per m²** in a specific city or district.
- Measure **sales growth** over several years.
- Evaluate **rental market volatility**.
- Assess **seasonal dynamics** of listings or sales activity.

#### Summary
`get_time_series_operations` retrieves **aggregated real-estate time-series data**
for a defined location or segment and computes selected analytical operations.
It provides a structured, quantitative summary of market trends and changes
for a single region or subset.

## Parameters

- `request_data` (object, required): Schema for MCP time-series analytical requests. ### Concept This schema defines *what* to analyze (via `filter`), *where* to analyze (via `segment`), and *which operations* to compute (via `operations`). - The `filter` contains **shared analytical parameters** defining the general query context. - The `segment` represents a **specific analytical subset** (e.g., a district, city, or region), which inherits all values from `filter` but can override a few (e.g., location boundary). This logic ensures a consistent analytical context while allowing a single location-specific override — suitable for focused analytical requests where only one boundary or subset is being analyzed.
  - `segment` (object, required): Analytical segment representing a boundary or subset of data. Inherits all fields from `filter` but may redefine location-specific ones (such as `custom_location_boundary` or `alias`).
    - `type_group` (string, required): Estate type group. Values: `apartment`, `house`.
    - `business_type` (string, required): Operation type for which the property is available. Values: `sale`, `rent`.
    - `price_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–2147483647.
      - `max` (integer, optional, nullable) 1–2147483647.
    - `price_per_sqm_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–2147483647.
      - `max` (integer, optional, nullable) 1–2147483647.
    - `rooms_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–15000.
      - `max` (integer, optional, nullable) 1–15000.
    - `bedrooms_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 0–15000.
      - `max` (integer, optional, nullable) 0–15000.
    - `bathrooms_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–15000.
      - `max` (integer, optional, nullable) 1–15000.
    - `total_area_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–1000000.
      - `max` (integer, optional, nullable) 1–1000000.
    - `plot_area_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–1000000.
      - `max` (integer, optional, nullable) 1–1000000.
    - `construction_year_range` (object, optional, nullable)
      - `min` (integer, optional, nullable) 1–3000.
      - `max` (integer, optional, nullable) 1–3000.
    - `characteristics` (object, optional, nullable)
      - `must_have` (string[], optional): Include only properties that have all these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
      - `exclude` (string[], optional): Exclude properties that contain any of these characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`.
    - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. at least 1 item.
    - `private` (boolean, optional): Whether the property is listed by a private individual, as opposed to an agent or a professional.
    - `bank` (boolean, optional): Whether the property is owned by the bank.
    - `auction` (boolean, optional): Whether the property is the subject of an auction. default false.
    - `exclude_outliers` (boolean, optional): Exclude properties that are significantly underpriced or overpriced compared to similar properties. default true.
    - `alias` (string, required): Alias (name) of the segment that was analyzed.
    - `custom_location_boundary` (object, required): Geographic boundary definition (circle, or location ID list).
      - `location_ids` (integer[], optional): List of location IDs. 1–10 items; 1–2147483647.
      - `circle` (object, optional): Circle boundary to search within.
        - `distance` (integer, required): Maximum distance in meters from the requested `target_point` to the properties. 50–50000.
        - `target_point` (object, required): Target point coordinates to search around.
          - `latitude` (number, required) -90–90.
          - `longitude` (number, required) -180–180.
    - `data_point` (string, required): Specifies the type of real estate data to retrieve for a given period. Values: `avg_price`, `avg_price_psqm`, `available_on_market`, `new`, `sold_or_rented`, `price_up`, `price_down`.
    - `date_interval` (string, required): Defines the time interval for aggregating data points. Determines the frequency at which data is reported in the response. Values: `week`, `month`, `quarter`, `year`.
    - `date_range` (object, required)
      - `min` (string (date), required): Start date in the format `YYYY-MM-DD`. If the specified date is not Monday - the closest previous Monday will be selected.
      - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`. If the specified date is not Sunday - the closest previous Sunday will be selected.
  - `operations` (string[], optional): List of analytical operations to compute (e.g. `mean`, `cagr`, `delta_pct`). If omitted, a default minimal set is applied. Values: `mean`, `median`, `std`, `var`, `min`, `max`, `sum`, `count`, `delta_abs`, `delta_pct`, `cagr`, `mom_last`, `yoy_last`, `slope_per_period`, `trend_strength`, `cv`, `inc_steps`, `dec_steps`, `flat_steps`, `p10`, `q1`, `p90`, `p95`, `iqr`, `outlier_ratio`, `zscore_max`, `movavg_last_3`, `movavg_last_6`, `movavg_last_12`.

## Response



- `alias` (string, required): Alias (name) of the segment that was analyzed.
- `date_start` (string (date), required): Start date of the analyzed period.
- `date_end` (string (date), required): End date of the analyzed period.
- `date_interval` (string, required): Frequency of the analyzed period. Values: `week`, `month`, `quarter`, `year`.
- `total_of_data_points` (integer, required): Number of data points included in the analyzed period.
- `results` (object[], required): List of computed results for each analytical operation.
  - `operation` (string, required): Operation type applied to the time series (e.g., mean, cagr, delta_pct, cv). Values: `mean`, `median`, `std`, `var`, `min`, `max`, `sum`, `count`, `delta_abs`, `delta_pct`, `cagr`, `mom_last`, `yoy_last`, `slope_per_period`, `trend_strength`, `cv`, `inc_steps`, `dec_steps`, `flat_steps`, `p10`, `q1`, `p90`, `p95`, `iqr`, `outlier_ratio`, `zscore_max`, `movavg_last_3`, `movavg_last_6`, `movavg_last_12`.
  - `value` (number, required): Computed numeric value. None if insufficient data for the operation.

## Example call

Required arguments only, with placeholder values; see the parameters above for real ones.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ma_get_time_series_operations",
    "arguments": {
      "request_data": {
        "segment": {
          "type_group": "apartment",
          "business_type": "sale",
          "alias": "…",
          "custom_location_boundary": {
            "location_ids": [
              1
            ]
          },
          "data_point": "avg_price",
          "date_interval": "week",
          "date_range": {
            "min": "2025-01-01"
          }
        }
      }
    }
  }
}
```

## Questions about this

- [What is Area Insights?](/docs/faq/what-is-area-insights)
- [Which tools exist only over MCP, and which operations only over REST?](/docs/faq/mcp-only-and-rest-only)
- [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend)