Over REST: no operation in the public API description does this. MCP and REST compared.
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
ToolErrorwill be raised. - Use returned data for map visualization or spatial analytics dashboards.
Returns
[
{
"location_id": 12345,
"location_name": "Lisbon",
"value": 5200.5
}
]Each item represents one geographic unit with aggregated metric value.
Parameters
request_dataobjectrequired19 properties
type_groupstringrequiredEstate type group.
apartment housebusiness_typestringrequiredOperation type for which the property is available.
sale rentprice_rangeobjectnullable2 properties
minintegernullable1–2147483647
maxintegernullable1–2147483647
price_per_sqm_rangeobjectnullable2 properties
minintegernullable1–2147483647
maxintegernullable1–2147483647
rooms_rangeobjectnullable2 properties
minintegernullable1–15000
maxintegernullable1–15000
bedrooms_rangeobjectnullable2 properties
minintegernullable0–15000
maxintegernullable0–15000
bathrooms_rangeobjectnullable2 properties
minintegernullable1–15000
maxintegernullable1–15000
total_area_rangeobjectnullable2 properties
minintegernullable1–1000000
maxintegernullable1–1000000
plot_area_rangeobjectnullable2 properties
minintegernullable1–1000000
maxintegernullable1–1000000
construction_year_rangeobjectnullable2 properties
minintegernullable1–3000
maxintegernullable1–3000
characteristicsobjectnullable2 properties
must_havestring[]Include only properties that have all these characteristics.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuityexcludestring[]Exclude properties that contain any of these characteristics.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuityconditionsstring[]Property conditions, as returned by the GET /api/v1/references/conditions endpoint.
used ruin very-good new otherat least 1 item
privatebooleanWhether the property is listed by a private individual, as opposed to an agent or a professional.
bankbooleanWhether the property is owned by the bank.
auctionbooleanWhether the property is the subject of an auction.
default false
exclude_outliersbooleanExclude properties that are significantly underpriced or overpriced compared to similar properties.
default true
location_idintegerrequired1–2147483647
data_pointstringrequiredSpecifies the type of real estate data to retrieve for a given period.
avg_price avg_price_psqm available_on_market new sold_or_rented price_up price_downdate_rangeobjectrequired2 properties
minstring (date)requiredStart date in the format
YYYY-MM-DD. If the specified date is not Monday - the closest previous Monday will be selectedmaxstring (date)nullableEnd date in the format
YYYY-MM-DD. If the specified date is not Sunday - the closest previous Sunday will be selectedResponse
Returned as result.
Show the response shape (3 fields)
location_idintegerrequiredlocation_namestringrequiredvaluenumberrequiredExample call
Required arguments only, with placeholder values. Your assistant fills them in from the parameters above.
{
"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"
}
}
}
}
}