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_fallbackis 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"
}
]
}
]
}