# `ma_get_time_on_market_distribution`

> **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 on Market Distribution. Product: [Area Insights](/docs/area-insights). Annotations: Read-only.

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

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

## Description

Returns a **distribution of properties by their time on the market**, grouped by price intervals.
Each record contains average listing duration and property count.

#### Business Context
Useful for evaluating **market liquidity** and **demand efficiency**,
identifying price segments where listings sell faster or remain longer.

#### Parameters
| Name | Type | Required | Description |
|------|------|-----------|--------------|
| `request_data` | `MCPTimeOnMarketDistributionRequestSchema` | Yes | Defines filters for listing duration analysis. |

##### Filter highlights
- `type_group`: property type group
- `business_type`: `"sale"` or `"rent"`
- `price_range`: price interval boundaries
- `date_range`: date range for the active listing period
- `exclude_outliers`: optional flag to exclude statistical outliers

#### Returns
```json
[
  {
    "lower_bound": 100000,
    "upper_bound": 199999,
    "days_on_market": 45,
    "months_on_market": 1.5,
    "properties_count": 120
  }
]
```

| Field | Type | Description |
|---------------|-------|------------|
| `lower_bound` | `int` | Lower price limit |
| `upper_bound` | `int` | Upper price limit |
| `days_on_market` | `int` | Average number of active days |
| `months_on_market` | `float` | Average duration in months |
| `properties_count` | `int` | Number of listings in the group |

#### Example Request
```json
{
  "custom_location_boundary": {
    "circle": {
      "target_point": {"latitude": 41.3851, "longitude": 2.1734},
      "distance": 20000
    }
  },
  "type_group": "apartment",
  "business_type": "sale",
  "price_range": {"min": 100000, "max": 1000000},
  "date_range": {"min": "2024-01-01", "max": "2024-12-31"},
  "exclude_outliers": true
}
```

## Parameters

- `request_data` (object, required)
  - `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.
  - `custom_location_boundary` (object, required)
    - `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.
  - `date_range` (object, optional): Filter properties based on the start date of their last active period on the market.
    - `min` (string (date), required): Start date in the format `YYYY-MM-DD`.
    - `max` (string (date), optional, nullable): End date in the format `YYYY-MM-DD`.

## Response

The result is returned as `result`:

- `lower_bound` (integer, required): The lower price bound of the distribution unit.
- `upper_bound` (integer, required): The upper price bound of the distribution unit.
- `days_on_market` (integer, required): The average days on the market.
- `months_on_market` (number, required): The average months on the market.
- `properties_count` (integer, required): The number of properties that participated in the distribution.

## 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_on_market_distribution",
    "arguments": {
      "request_data": {
        "type_group": "apartment",
        "business_type": "sale",
        "custom_location_boundary": {
          "location_ids": [
            1
          ]
        }
      }
    }
  }
}
```

## Questions about this

- [What is Area Insights?](/docs/faq/what-is-area-insights)
- [How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap)