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.
- Read the Taxonomies once, to resolve the codifications the creation expects.
- Create the report for the property you want to analyse. The response contains the
report_uuid. - 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.
- Request any block of that report by passing the UUID in the path:
/api/report/appraisal/<report_uuid>/<block>. - 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.
Do not hardcode the icon host
The markerIconOptions.iconUrl of the examples in this section points to pdf-generator-dev.realitycs.it, because the examples were captured on the sandbox. The host differs between environments, so always use the URL as it arrives in the response rather than rebuilding it, and never pin it in your client.
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.