Sales Price History
POST /api/sales/price/history
Historical time series of sale prices.
Example Request
curl --location 'https://ws-osservatorio.realitycs.it/api/sales/price/history' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"ty_zone": "com",
"id_zone": "100005",
"window": "1M",
"contract": 1,
"year": 2024,
"month": 12,
"typology": 4,
"nation": "IT"
}'
Request Fields
| Field | Required | Default | Description | Type | Example | Notes |
|---|---|---|---|---|---|---|
ty_zone | yes | Zone type | string | com | ||
id_zone | yes | Zone ID | string | 100005 | ||
window | yes | Time window | string | 1M | ||
contract | yes | Contract type | number | 1 | ||
year | yes | Required year | number | 2024 | ||
month | yes | Required month | number | 12 | ||
cadastral_typology | optional | Estate cadastral typology | string | A4 | ||
nation | optional | IT | Nation code | string | IT | |
allow_geo_fallback | optional | false | Look for data in higher geographic levels if the requested zone has not enough data | boolean | false | See Geographic Fallback |
geo_fallback_threshold | optional | 4 | Maximum number of missing periods tolerated in a series (0–13). Used only if allow_geo_fallback is true, otherwise ignored | number | 4 | See Geographic Fallback |
Geographic Fallback
History series contain 13 periods: the requested one plus the 12 preceding ones. By default only the requested zone is searched.
With allow_geo_fallback set to true, a series is accepted only 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). Otherwise the API goes up one geographic level at a time (micro → macro → com → pro → reg → naz) until the series is sufficient.
geo_fallback_threshold is used only when allow_geo_fallback is true; otherwise it is ignored.
geo_fallback_threshold | Minimum periods required (out of 13) |
|---|---|
0 | 13 |
4 (default) | 9 |
13 | 0 (the fallback never triggers for lack of periods) |
- Each key of the response is evaluated independently, so different keys can come from different zones.
- The zone of each series is returned in the
ty_zoneandid_zonefields of every element. At national levelty_zoneisnazandid_zoneis0. - If a key still has insufficient data at national level, a
400error (data is missing or unavailable) is returned. allow_geo_fallbackmust be a boolean andgeo_fallback_thresholdan integer between 0 and 13; any other value returns a400error.
For the full description see Taxonomies.
JSON keys in the response:
- compravendite_price_sqm_avg: Average transaction price.
Every element of every series also contains ty_zone and id_zone: the zone the series belongs to, which may differ from the requested one when allow_geo_fallback is used.
Example Response
{
"_metadata": {
"message": "",
"query": {},
"status": 200,
"request_id": "7cb8255e-c582-43bf-a978-ca15381f7ded"
},
"items": [
{
"compravendite_price_sqm_avg": [
{
"id_zone": "100005",
"month": 6,
"price_avg": 1453,
"ty_zone": "com",
"year": 2020
},
{
"id_zone": "100005",
"month": 9,
"price_avg": 1431,
"ty_zone": "com",
"year": 2020
},
{
"id_zone": "100005",
"month": 12,
"price_avg": 1483,
"ty_zone": "com",
"year": 2020
},
{
"id_zone": "100005",
"month": 3,
"price_avg": 1482,
"ty_zone": "com",
"year": 2021
},
{
"id_zone": "100005",
"month": 6,
"price_avg": 1478,
"ty_zone": "com",
"year": 2021
},
{
"id_zone": "100005",
"month": 9,
"price_avg": 1500,
"ty_zone": "com",
"year": 2021
},
{
"id_zone": "100005",
"month": 12,
"price_avg": 1514,
"ty_zone": "com",
"year": 2021
},
{
"id_zone": "100005",
"month": 3,
"price_avg": 1503,
"ty_zone": "com",
"year": 2022
},
{
"id_zone": "100005",
"month": 6,
"price_avg": 1538,
"ty_zone": "com",
"year": 2022
},
{
"id_zone": "100005",
"month": 9,
"price_avg": 1512,
"ty_zone": "com",
"year": 2022
},
{
"id_zone": "100005",
"month": 12,
"price_avg": 1485,
"ty_zone": "com",
"year": 2022
},
{
"id_zone": "100005",
"month": 3,
"price_avg": 1492,
"ty_zone": "com",
"year": 2023
},
{
"id_zone": "100005",
"month": 6,
"price_avg": 1469,
"ty_zone": "com",
"year": 2023
}
]
}
]
}