# `ma_get_time_series_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).

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

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

Over REST: [`POST /market-analytics-api/time-series`](/docs/rest/area-insights/time-series) (equivalent). [MCP and REST compared](/docs/parity#area-insights).

## Description

Retrieve **time series data** for the real estate market.
Each data point in the series represents an aggregated metric (`data_point`) for a specific period,
defined by the chosen `date_interval` and property filters.

This tool provides consistent, interval-based historical data for various real estate indicators.

#### Use Cases
Retrieve historical market information, such as:
- Average property prices.
- Average price per square meter.
- Number of properties sold or rented over time.
- Number of newly listed properties.
- Number of properties available on the market.
- Number of price increases or decreases for listings.

#### Parameters
| Name | Type | Required | Description |
|------|------|-----------|--------------|
| `request_data` | `MCPTimeSeriesRequestSchema` | Yes | Defines filters, time interval, and data metric (`data_point`) for aggregation. |

##### Filter highlights
- `data_point`: defines **which metric** to retrieve (e.g. price, listings, sold count, etc.).
- `date_interval`: defines **the frequency** of data points in the response (`WEEK`, `MONTH`, `QUARTER`, `YEAR`).
- `custom_location_boundary`: spatial boundary (circle or list of location IDs).
- `type_group`: group of property types to analyze.
- `business_type`: `"sale"` or `"rent"`.
- `exclude_outliers`: optionally exclude statistical outliers from the results.
- optional property filters: price range, area, bedrooms, bathrooms, etc.

#### Important Notes
- If you need to compare different property types, send **separate requests** for each type group.
- For broader analyses, prefer using `AVERAGE_PRICE_PER_SQM` over total price.
- You can reuse the same filters with different `data_point` values to analyze multiple aspects of the market
(e.g. compare new listings vs. sold properties).
- Use the `exclude_outliers` flag to remove extreme values and improve analytical accuracy.

#### Returns
```json
[
  {
    "date_start": "2024-01-01",
    "value": 4350.5
  }
]

## Parameters

- `request_data` (object, required): One analytical segment defining a specific filter or location boundary. Alias (name) is generated automatically on the server based on the location definition.
  - `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.

## Response

The result is returned as `result`:

- `date_start` (string (date), required): The starting date of the period associated with the passed `date_interval` field value. The format follows `YYYY-MM-DD`.
- `value` (number, required): The numerical value corresponding to the passed `data_point` field value for the given `date_start`.

## 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_data",
    "arguments": {
      "request_data": {
        "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)
- [How do I analyse how prices in an area have moved over time?](/docs/faq/example-price-trend)