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)
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)
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
}