Getting started

Welcome to the Property Risk documentation. Use the left navigation to browse endpoints and guides.

Environments

PRODUCTIONSANDBOX

http://ws-rischio.realitycs.it

http://ws-rischio-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

The service quantifies the exposure of a property to a set of natural hazards. It is built on three layers, each answering a different question and each exposed by its own endpoint:

Layer	Question it answers	Unit
Danger	How dangerous is this position?	Index, 0 to 1
Vulnerability	How much would this property suffer, given that danger?	Index, 0 to 1
Risk	How much value is at stake?	Euro

Danger depends only on the position, so it needs nothing but the coordinates. Vulnerability also takes the characteristics of the building into account. Risk combines the two with the value of the property, and is therefore the only endpoint requiring property_value.

The same hazards are reported by all three layers, around 27 of them, from earthquake and flood to heat_wave and subsidence.

Single and multiple

Every endpoint comes in two flavours: one asset per call, and many assets per call.

Single	Multiple
Danger	Danger multiple
Vulnerability	Vulnerability multiple
Risk	Risk multiple

The single variants take the asset fields at the top level of the body. The multiple variants take a features array, one entry per asset, with the shared fields such as nation left outside it. Prefer the multiple variants for batches: same data, one round trip.

Request format

All the endpoints are POST calls taking a JSON body:

Content-Type: application/json

Common request fields

Field	Required	Default	Description	Type	Example	Notes
`lat`	yes		Latitude	number	`41.8967068`
`lng`	yes		Longitude	number	`12.4822025`
`id_immobile`	optional		Your own asset id	string	`IMMO_SAMPLE_1`	See the note below
`nation`	optional	`IT`	Nation ID	string	`IT`	See Taxonomies
`property_value`	yes on Risk		Value of the property, in euro	integer	`245000`	Risk only
`maintenance_status`	optional		Maintenance condition	integer	`2`	See Taxonomies
`construction_year`	optional		Year of construction	integer	`1997`
`floor`	optional	`0`	Floor of the unit	integer	`1`

Note

In requests and responses, where applicable, the key id_immobile represents an optional string ID used solely to identify elements in the received response.

The presence or absence of this key does NOT affect the outcome of the request and is entirely up to the caller.

If not provided in the request, one will be automatically generated.

Warning

Duplicate id_immobile values are not allowed within the same request.

Describing the building sharpens the answer

Beyond the coordinates, maintenance_status, construction_year and floor are optional but they are what makes vulnerability and risk specific to your property rather than generic for the position. Omitting them falls back to defaults, so pass them whenever you have them.

Response format

All the endpoints answer with the standard Insights envelope: _metadata describing the outcome, items holding one entry per asset.

Each entry has the same two blocks:

asset: echo of the input for that asset, id_immobile included, so results can be matched back to your own records.
properties: one key per hazard. Danger and Vulnerability name them after the hazard, while Risk prefixes them with property_value_risked_, since those values are amounts in euro rather than indices.

Match on id_immobile, not on order

The items array carries id_immobile inside asset precisely so you do not have to rely on positional matching. Use it as the join key, especially with the multiple variants.

Zero means not exposed

A hazard reported as 0 means the property is not exposed to it at that position, which is the normal case for most hazards: an inland property returns 0 for coastal_flooding. Treat zeros as information, not as missing data.

Changes

All updates to the endpoints are tracked in the Changelog.