Skip to content

Getting started

Welcome to the Report Pro documentation. Use the left navigation to browse endpoints and guides.

Environments

https://insights.immobiliare.it

http://explore-b2c-dev-be.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

The report is a resource identified by a UUID. Once a report has been created, its content is exposed as a set of independent blocks: each endpoint in this section returns one block of the same report, so a client can load only the pages it needs and can load them in parallel.

  1. Read the Taxonomies once, to resolve the codifications the creation expects.
  2. Create the report for the property you want to analyse. The response contains the report_uuid.
  3. Wait for the generation to complete, polling Report status or declaring a callback. The creation is asynchronous unless you ask for it not to be.
  4. Request any block of that report by passing the UUID in the path: /api/report/appraisal/<report_uuid>/<block>.
  5. Alternatively, download the whole report as a PDF laid out with the Immobiliare.it Insights template.

Blocks are not available immediately

Requesting a block of a report that is still being generated answers 400 with error_code DATA_NOT_EXIST. Always confirm the report is ready before reading it, see Report status.

Block Content
AVM Estimated value, suggested asking price, rent and return
Property info Attributes of the valued property, ratings, surface analysis
OMI Official Agenzia delle Entrate quotations
Market Supply, demand and price dynamics of the zone
Comparables Comparable listings currently on the market
Sales Comparable transactions actually closed
Services Amenities and transport around the property
Population Demographics of the surrounding area
Energy Energy class distribution and green premium
Geographical data GeoJSON layers for the OMI and market zone maps

The report is also available as a ready made document, see Report PDF download.

Request format

Every block is read with a GET and takes no request body. The report_uuid always travels as a path parameter.

GET /api/report/appraisal/<report_uuid>/<block>

Common request fields

Field Required Default Description Type Example Notes
report_uuid yes UUID of the report, given during the creation string e75ad7d5-dad2-4f6c-8db8-02295bd0bd9f Path parameter
show_geo optional false Adds the geometrical data of the block to the response any ?show_geo=1 Only on some blocks, see below

show_geo

show_geo is a flag: any value enables it, its presence in the query string is what counts. It only affects four blocks, and what it adds differs from one to another:

Block Added by show_geo
Property info lat and lng of the property
Services services_map layer
Comparables comparables_map layer
Sales sales_map layer

On every other block it is accepted and ignored. Geographical data always returns its layers and needs no flag.

Response format

All the endpoints answer with the standard Insights envelope: a _metadata object describing the outcome and a data object holding the payload of the block.

{
  "_metadata": {
    "message": "",
    "query": {},
    "status": 200
  },
  "data": {}
}

Map layers are GeoJSON

Every *_map key, and both layers of Geographical data, is a GeoJSON FeatureCollection. Coordinates follow the GeoJSON convention and are ordered longitude first, then latitude. Features carry rendering hints alongside the geometry: markerIconOptions for points and pathOptions for polygons.

Localised content

Labels and descriptive texts are returned already localised in Italian and are meant to be displayed as they are: keys such as label, title, description, category and population_description hold presentation strings, not codes. Identifiers to switch logic on are exposed separately, in id or categoryId.

Errors

See the general Error Handling page.