Skip to content

Taxonomies

Use these values in requests.

Month Dictionary (month)

Window Allowed Months Meaning
1M (Monthly) 1–12 Any month
3M (Quarterly) 3, 6, 9, 12 End of quarter
6M (Semiannual) 6, 12 End of semester
12M (Annual) 12 End of calendar year

Examples

Period Month Year Result
3M 12 2024 Last quarter of 2024
3M 3 2024 First quarter of 2024
6M 12 2024 Second semester of 2024
12M 12 2024 Year 2024
3M 2 2024 Not allowed
6M 11 2024 Not allowed

Nation (nation)

ID Value
IT Italy

Typology (typology)

ID Value
4 Apartment
5 Penthouse / Attic
7 Detached House
10 Building / Palace
11 Rustic / Farmhouse
12 Villa
13 Terraced House
31 Loft / Open Space
110 Shops
140 Offices

Contract (contract)

ID Value
1 Sale
2 Rent

Maintenance Status (maintenance_status)

ID Value
1 New / Under Construction
2 Excellent / Renovated
3 Good / Habitable
4 Not Renovated

Cadastral Typologies (cadastral_typologies)

ID Value
A1 A1 – High-end residences
A2 A2 – Standard residences
A3 A3 – Economic residences
A4 A4 – Public housing
A5 A5 – Very low-end residences
A6 A6 – Rural residences
A7 A7 – Small villas
A8 A8 – Villas
A9 A9 – Castles / buildings of outstanding artistic or historical value
A11 A11 – Typical local dwellings

Surface Class (class_surface)

ID Value
1 Less than 50 m²
2 50–85 m²
3 85–115 m²
4 115–145 m²
5 Over 145 m²

Zone Type (ty_zone)

ID Value
reg Region
pro Province
com Municipality
macro Macro-zone
micro Micro-zone

Window (window)

ID Value
1M Monthly
3M Quarterly
6M Semiannual
12M Annual

Segmentation (segmentation)

ID Value
not_segmented Not segmented data
energy Segmentation by energy class (high, medium, low)

Geographic Fallback

When the requested zone has no data, or not enough of it, the API can automatically look for the data in the next higher geographic level. This behavior is optional and disabled by default.

Parameters

Parameter Type Default Description
allow_geo_fallback boolean false Enables the search in higher geographic levels when the requested zone has no sufficient data
geo_fallback_threshold integer 4 Maximum number of missing periods tolerated in a history series (0–13). History endpoints only. Used only if allow_geo_fallback is true, otherwise ignored

Both parameters are optional. null or omitted values are treated as the default.

Supported endpoints

Parameter Endpoints
allow_geo_fallback /api/price, /api/price/history, /api/price/forecast, /api/ads, /api/ads/history, /api/search-data, /api/search-data/history, /api/sales/price, /api/sales/price/history, /api/sales/volume, /api/sales/volume/history, /api/energy
geo_fallback_threshold /api/price/history, /api/ads/history, /api/search-data/history, /api/sales/price/history, /api/sales/volume/history

Geographic levels

The search goes up one level at a time and stops at the first zone that has the data.

Requested zone (ty_zone) Next level tried
micro macro
macro com
com pro
pro reg
reg naz

If no data is found even at national level, the request fails with a 400 error (data is missing or unavailable).

allow_geo_fallback

  • false (default): only the requested zone is searched. If it has no data, the API returns the usual 400 error (or an empty response when success_if_empty is true).
  • true: if the requested zone has no data, the API tries the higher levels listed above.

When the fallback is used, the data may belong to a zone different from the requested one. The zone actually used is always returned in the response fields ty_zone and id_zone.

Constraints

  • allow_geo_fallback must be a boolean. Any other type (for example the string "true") returns a 400 error.
  • In the endpoints that accept success_if_empty (price, ads, search-data, sales/price, sales/volume), allow_geo_fallback and success_if_empty cannot both be true.

geo_fallback_threshold

History series contain 13 periods: the requested one plus the 12 preceding ones. geo_fallback_threshold is the maximum number of periods that may be missing in a series before the API considers it insufficient and searches the higher level. A series is accepted if it has at least 13 - geo_fallback_threshold periods with data.

A period has data if at least one field other than year and month is not null.

geo_fallback_threshold Minimum periods required (out of 13) Effect
0 13 Strictest: any missing period moves the series to a higher level
4 (default) 9 Up to 4 missing periods are tolerated
13 0 No minimum: the fallback is never triggered for lack of periods

Behavior

  • It is used only when allow_geo_fallback is true. Otherwise it is ignored.
  • Each key of the response (for example price_sqm_avg, maintenance_status, rooms) is evaluated independently. One key can stay on the requested zone while another moves to a higher level, so the ty_zone and id_zone of each series may differ from key to key.
  • For keys that contain several series (maintenance_status, rooms), the series with the fewest periods decides: if one is too short, the whole key moves to the higher level, so all its series come from the same zone.
  • The rooms key is available for residential requests only. For other types it is always empty and never triggers the fallback.
  • It must be an integer between 0 and 13. Any other value (string, decimal, boolean, out of range) returns a 400 error when allow_geo_fallback is true.
  • If, after reaching the national level, at least one key still has insufficient data, the request fails with a 400 error (data is missing or unavailable).

Example

{
  "ty_zone": "com",
  "id_zone": "12345678",
  "contract": 1,
  "window": "6M",
  "year": 2026,
  "month": 6,
  "allow_geo_fallback": true,
  "geo_fallback_threshold": 2
}