Heatmap of an area by district
POST
https://platform.casafari.com/v1/area-insights/heatmapAPI key25 tokens a call39 parameters
Send Authorization: Bearer $CASAFARI_API_KEY: a platform API key (cf_sk_...) from the console, or an OAuth access token; X-API-Key carries the key too. See platform API keys. Costs 25 tokens a call (1 token = EUR 0.04).
The platform's OpenAPI file leaves the shape open; what is shown comes from the same definitions the platform publishes elsewhere: request: the MCP tool area-insights_get_heatmap's input (its request_data object).
Over MCP: area-insights_get_heatmap (equivalent). See MCP and REST compared.
Description
Costs 25 tokens a call.
Request body
Content type application/json. Optional. Type: object.
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 selectedExample request
Placeholders only: replace the token and the values with your own.
curl -X POST "https://platform.casafari.com/v1/area-insights/heatmap" \
-H "Authorization: Bearer $CASAFARI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type_group": "apartment",
"business_type": "sale",
"location_id": 1,
"data_point": "avg_price",
"date_range": {
"min": "2025-01-01"
}
}'Responses
200 Success.
Type: object.
Errors
Every error is an application/problem+json body (RFC 9457) with type (a page that explains it), title, status, detail (what to do), instance, code and request_id (what to quote to support). A 402 carries an upgrade_url, a 429 a Retry-After header. The codes each status can carry:
- 400
invalid_request,key_in_query(https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query) - 401
unauthorized,invalid_credential,credential_revoked,token_expired(https://platform.casafari.com/errors/unauthorized, https://platform.casafari.com/errors/invalid-credential, https://platform.casafari.com/errors/credential-revoked, https://platform.casafari.com/errors/token-expired) - 402
payment_required(https://platform.casafari.com/errors/payment-required) - 403
insufficient_scope,not_entitled,account_suspended(https://platform.casafari.com/errors/insufficient-scope, https://platform.casafari.com/errors/not-entitled, https://platform.casafari.com/errors/account-suspended) - 404
not_found(https://platform.casafari.com/errors/not-found) - 405
method_not_allowed(https://platform.casafari.com/errors/method-not-allowed) - 409
conflict(https://platform.casafari.com/errors/conflict) - 413
payload_too_large(https://platform.casafari.com/errors/payload-too-large) - 415
unsupported_media_type(https://platform.casafari.com/errors/unsupported-media-type) - 422
validation_failed(https://platform.casafari.com/errors/validation-failed) - 429
rate_limited,daily_limit_reached,request_limit_reached,usage_limit_reached(https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/daily-limit-reached, https://platform.casafari.com/errors/request-limit-reached, https://platform.casafari.com/errors/usage-limit-reached) - 500
internal_error(https://platform.casafari.com/errors/internal-error) - 502
upstream_error(https://platform.casafari.com/errors/upstream-error) - 503
capacity_exhausted,unavailable(https://platform.casafari.com/errors/capacity-exhausted, https://platform.casafari.com/errors/unavailable) - 504
upstream_timeout(https://platform.casafari.com/errors/upstream-timeout)