Skip to content

Sales Volume History

POST /api/sales/volume/history

Historical time series of transaction volumes.

Example Request

curl --location 'https://ws-osservatorio.realitycs.it/api/sales/volume/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_zone and id_zone fields of every element. At national level ty_zone is naz and id_zone is 0.
  • If a key still has insufficient data at national level, a 400 error (data is missing or unavailable) is returned.
  • allow_geo_fallback must be a boolean and geo_fallback_threshold an integer between 0 and 13; any other value returns a 400 error.

For the full description see Taxonomies.

JSON keys in the response:

  • sales_qtraw: NTN (rielab. dati AdE)

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": "4cc03232-7427-4f7e-ae64-762372e9e14b"
    },
    "items": [
        {
            "sales_qtraw": [
                {
                    "id_zone": "100005",
                    "month": 6,
                    "qtraw": 6046,
                    "ty_zone": "com",
                    "year": 2020
                },
                {
                    "id_zone": "100005",
                    "month": 9,
                    "qtraw": 6715,
                    "ty_zone": "com",
                    "year": 2020
                },
                {
                    "id_zone": "100005",
                    "month": 12,
                    "qtraw": 9226,
                    "ty_zone": "com",
                    "year": 2020
                },
                {
                    "id_zone": "100005",
                    "month": 3,
                    "qtraw": 7948,
                    "ty_zone": "com",
                    "year": 2021
                },
                {
                    "id_zone": "100005",
                    "month": 6,
                    "qtraw": 10048,
                    "ty_zone": "com",
                    "year": 2021
                },
                {
                    "id_zone": "100005",
                    "month": 9,
                    "qtraw": 8213,
                    "ty_zone": "com",
                    "year": 2021
                },
                {
                    "id_zone": "100005",
                    "month": 12,
                    "qtraw": 10650,
                    "ty_zone": "com",
                    "year": 2021
                },
                {
                    "id_zone": "100005",
                    "month": 3,
                    "qtraw": 8788,
                    "ty_zone": "com",
                    "year": 2022
                },
                {
                    "id_zone": "100005",
                    "month": 6,
                    "qtraw": 10181,
                    "ty_zone": "com",
                    "year": 2022
                },
                {
                    "id_zone": "100005",
                    "month": 9,
                    "qtraw": 8477,
                    "ty_zone": "com",
                    "year": 2022
                },
                {
                    "id_zone": "100005",
                    "month": 12,
                    "qtraw": 10469,
                    "ty_zone": "com",
                    "year": 2022
                },
                {
                    "id_zone": "100005",
                    "month": 3,
                    "qtraw": 8034,
                    "ty_zone": "com",
                    "year": 2023
                },
                {
                    "id_zone": "100005",
                    "month": 6,
                    "qtraw": 8952,
                    "ty_zone": "com",
                    "year": 2023
                }
            ]
        }
    ]
}