# `ma_get_heatmap`

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

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

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

## Description

Generate an **area insights heatmap** showing property distribution and price dynamics
across geographic areas.

This tool aggregates **active real estate listings** for the child locations of the given `location_id`
(e.g., districts of a city), returning the selected `data_point` metric for each of them.
It supports a wide range of property filters, including estate type, price range,
construction year, and location hierarchy.

#### Use Cases
Retrieve geographic insights for real estate analytics:
- Visualize market activity intensity across a city or region.
- Identify hotspots of high property density or high average price.
- Compare neighborhoods based on average price per sqm.
- Analyze supply distribution and property trends over time.
- Combine with time-series data to understand historical evolution by area.

#### Parameters
| Name | Type | Required | Description |
|------|------|-----------|--------------|
| `request_data` | `MCPHeatMapRequestSchema` | Yes | Defines filters, metrics, and date range for heatmap generation. |

#### Important Notes
- Only **ACTIVE** listings are included.
- The tool automatically resolves **child locations** (e.g., neighborhoods within a city).
- If no matching data is found, a `ToolError` will be raised.
- Use returned data for **map visualization** or **spatial analytics dashboards**.

#### Returns
```json
[
  {
    "location_id": 12345,
    "location_name": "Lisbon",
    "value": 5200.5
  }
]
```
Each item represents one geographic unit with aggregated metric value.

## 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.
  - `location_id` (integer, required) 1–2147483647.
  - `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_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`:

- `location_id` (integer, required)
- `location_name` (string, required)
- `value` (number, required)

## 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_heatmap",
    "arguments": {
      "request_data": {
        "type_group": "apartment",
        "business_type": "sale",
        "location_id": 1,
        "data_point": "avg_price",
        "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 see how properties are distributed by price, bedrooms or time on market, or get a heatmap?](/docs/faq/example-distributions-heatmap)
- [Can I build a market report with Casafari MCP?](/docs/faq/example-market-report)