Skip to content

Ads

POST /api/ads

Real estate listings stock infos.

Example Request

curl --location 'https://ws-osservatorio.realitycs.it/api/ads' \
--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
typology optional Estate typology number 4
nation optional IT Nation code string IT
success_if_empty optional false handle response with empty data boolean false
allow_geo_fallback optional false Look for data in higher geographic levels if the requested zone has none boolean false See Geographic Fallback. Cannot be true together with success_if_empty

Geographic Fallback

By default only the requested zone is searched. With allow_geo_fallback set to true, if the requested zone has no data the API goes up one geographic level at a time (micro → macro → com → pro → reg → naz) and returns the data of the first zone that has them. If no level has data, a 400 error (data is missing or unavailable) is returned.

The zone the data belongs to is returned in ty_zone and id_zone, and may differ from the requested one. When the fallback reaches the national level, ty_zone is naz and id_zone is 0.

allow_geo_fallback must be a boolean; any other type returns a 400 error. For the full description see Taxonomies.

JSON keys in the response:

  • absorption_index: Absorption Index.
  • maintenance_status: Maintenance condition.
  • oldness: Time on market.
  • persistence: Time to sell.
  • qt_in_pure: Number of new listings.
  • qt_inout: Absorption Index.
  • qt_out_pure: Number of exited listings.
  • qt_stb: Number of stable listings.
  • qtraw: Number of listings.
  • rooms: Number of rooms.
  • status_annunci: Stock renewal/stability.
  • typologies: Property typology.
  • ty_zone: Zone type the data belongs to (may differ from the requested one when allow_geo_fallback is used).
  • id_zone: ID of the zone the data belongs to.

Example Response

{
    "_metadata": {
        "message": "",
        "query": {},
        "status": 200,
        "request_id": "7d16e7fb-d42a-4985-95b7-231fee8a5297"
    },
    "items": [
        {
            "absorption_index": {
                "delta": {
                    "value": 0.33,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 6
                },
                "value": -0.08
            },
            "id_zone": "100005",
            "maintenance_status": [
                {
                    "qt_raw_perc": 44,
                    "status_id": "3"
                },
                {
                    "qt_raw_perc": 36,
                    "status_id": "2"
                },
                {
                    "qt_raw_perc": 9,
                    "status_id": "4"
                },
                {
                    "qt_raw_perc": 7,
                    "status_id": "1"
                },
                {
                    "qt_raw_perc": 4,
                    "status_id": "nd"
                }
            ],
            "oldness": {
                "delta": {
                    "value": 4.51,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 2
                },
                "value": 6.25
            },
            "persistence": {
                "delta": {
                    "value": -19.88,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 3
                },
                "value": 4.26
            },
            "qt_in_pure": {
                "delta": {
                    "value": 8.45,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 1
                },
                "value": 372
            },
            "qt_inout": {
                "delta": {
                    "value": -22.43,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 1
                },
                "value": 83
            },
            "qt_out_pure": {
                "delta": {
                    "value": 41.39,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 1
                },
                "value": 345
            },
            "qt_stb": {
                "delta": {
                    "value": -1.09,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 1
                },
                "value": 1537
            },
            "qtraw": {
                "delta": {
                    "value": 3.96,
                    "window": "1M"
                },
                "ranking": {
                    "of": 7,
                    "position": 1
                },
                "value": 2337
            },
            "rooms": [
                {
                    "qt_raw_perc": 30.0,
                    "room_id": "m5"
                },
                {
                    "qt_raw_perc": 26,
                    "room_id": "4"
                },
                {
                    "qt_raw_perc": 22,
                    "room_id": "5"
                },
                {
                    "qt_raw_perc": 13,
                    "room_id": "3"
                },
                {
                    "qt_raw_perc": 7,
                    "room_id": "2"
                },
                {
                    "qt_raw_perc": 1,
                    "room_id": "1"
                },
                {
                    "qt_raw_perc": 1,
                    "room_id": "nd"
                }
            ],
            "status_annunci": {
                "qt_dinamici_perc": 34,
                "qt_stb_perc": 66
            },
            "ty_zone": "com",
            "typologies": [
                {
                    "qt_raw_perc": 66.0,
                    "typology_id": "4"
                },
                {
                    "qt_raw_perc": 17,
                    "typology_id": "7"
                },
                {
                    "qt_raw_perc": 8,
                    "typology_id": "12"
                },
                {
                    "qt_raw_perc": 3,
                    "typology_id": "5"
                },
                {
                    "qt_raw_perc": 3,
                    "typology_id": "13"
                },
                {
                    "qt_raw_perc": 2,
                    "typology_id": "11"
                },
                {
                    "qt_raw_perc": 1,
                    "typology_id": "10"
                },
                {
                    "qt_raw_perc": 0,
                    "typology_id": "31"
                }
            ]
        }
    ]
}