Skip to content

Getting started

Welcome to the Market Explorer documentation. Use the left navigation to browse endpoints and guides.

Environments

https://ws-osservatorio.realitycs.it

https://ws-osservatorio-dev.realitycs.it

All the requests do require an OAUTH 2.0 auth token in the header, see the authentication page for details.

How it works

Market Explorer answers questions about the real estate market of an area over a period. There is nothing to create: every call is self contained and identifies what you want through the same handful of coordinates.

  1. Resolve the area you are interested in, see Locating the area below.
  2. Pick the period: a window, a year and a month.
  3. Call the indicator you need.
Indicator Content
Price Asking prices of the listings
Price Forecast Forecast of the asking prices
Ads Stock of listings on the market
Search Data Demand, as expressed by the searches of the users
Sales Price Prices of the closed transactions
Sales Volume Number of closed transactions

Every indicator except the forecast also comes in a History variant, which returns the series over time instead of the single period: Price History, Ads History, Search Data History, Sales Price History, Sales Volume History. The request is the same, so switching from a value to its series only means changing the path.

Request format

Indicators are POST calls taking a JSON body, taxonomies are GET calls with the parameters in the path:

Content-Type: application/json

Common request fields

Field Required Default Description Type Example Notes
ty_zone yes Zone type string com See Taxonomies
id_zone yes Identifier of the zone, within that zone type string 100005
window yes Time window string 1M 1M, 3M, 6M, 12M
year yes Year of the period number 2024
month yes Month closing the period number 12 Constrained by window
contract yes Contract type number 1 1 sale, 2 rent
typology optional Property typology number 4 See Taxonomies
nation optional IT Nation code string IT
success_if_empty optional false Answer successfully when there is no data for the query boolean false

Locating the area

ty_zone and id_zone always travel together: the first says which level of the geography you are addressing, the second identifies the zone at that level. The levels go from reg (region) down to micro (micro-zone), see Taxonomies.

There are two ways to obtain an id_zone:

Coming from coordinates?

If your input is a property rather than a zone, Taxonomies geographical hierarchy is the shortest route: one call turns lat and lng into the ids of every level the point belongs to, which you then feed to the indicators.

Choosing the period

window sets the granularity and month has to be the month closing that period. The two are not independent:

window Allowed month Meaning
1M 1 – 12 Any month
3M 3, 6, 9, 12 End of quarter
6M 6, 12 End of semester
12M 12 End of calendar year

Mismatched window and month are rejected

3M with month 2, or 6M with month 11, are not valid combinations: a quarter can only close in March, June, September or December, and a semester only in June or December. Validate the pair before calling, see Taxonomies for the full dictionary and further examples.

Not every period is available for every indicator

Taxonomies Temporal declares, year by year, which datasets are actually populated. Read it when a query comes back empty, before concluding the area has no data.

Codified fields

ty_zone, window, contract, typology, maintenance_status, cadastral_typologies, class_surface, segmentation and nation are codified. Taxonomies lists the values as reference tables, and Taxonomies General returns the same sets from the API when you prefer to resolve them at runtime.

Response format

All the endpoints answer with the standard Insights envelope: _metadata describing the outcome, items holding the results.

{
  "_metadata": {
    "message": "",
    "query": {},
    "status": 200,
    "request_id": "1eb7d444-17a7-4808-83e7-8b6ba3c51637"
  },
  "items": []
}

Empty results are an error by default

When there is no data for the combination you asked for, the call fails rather than returning an empty items. Set success_if_empty to true to get a successful response with no data instead, which is usually what you want when you are sweeping many zones or periods in a loop.

Changes

All updates to the endpoints are tracked in the Changelog.