Integrations: the report inside your software and your website

The report fits into the tools an agency already uses in three ways, from the simplest to the most complete: a link with the address, which anyone can add to a property record or an email; the liveability index widget for the listings on your website; and the API, to create reports and download the PDFs straight from your property management software (gestionale). Below is how each one works, with examples ready to copy.

A link with the address

The property page opens with the search already done when the address is in the link. For example, this one opens Via Dante 7 in Milan: it shows the plot on the map, the cadastral sheet and parcel and the liveability index of the area, and from there you create the full report.

The link accepts three ways of pointing to the property:

For a plot of land add &tipo=terreno, and the page starts from the land summary with area, slope and elevation. The municipality code is the six-digit Istat code, the same one used in cadastral data. Spaces and commas in the address must be URL-encoded, which any programming language does for you.

In agency software, a button on the property record that builds the link from the record's address is all it takes:

<a href="https://vicinalia.com/immobile?indirizzo=ENCODED_STREET_NUMBER_TOWN" target="_blank" rel="noopener">Check the area</a>

The partner link

Members of the partner programme add their code to the link, with &rif= followed by their personal code. The customer lands on the property page, the site remembers who sent them, and on their first purchase the partner earns the commission. For a software supplier it means offering clients one more service and earning on every new customer who uses it:

https://vicinalia.com/immobile?indirizzo=Via%20Dante%207%2C%20Milano&rif=CODE

The liveability index widget

With the Pro and Studio plans an agency can show the liveability index of the area, from 0 to 100 with its band, in the listings on its own website. The widget is a page embedded with an iframe: register your website's domain in Settings, Widget, and you get a key that works only on that domain.

<iframe src="https://vicinalia.com/widget/vivibilita?chiave=YOUR_KEY&indirizzo=Via%20Dante%207%2C%20Milano&lingua=en" width="360" height="220" style="border:0" loading="lazy" title="Liveability index of the area"></iframe>

Instead of the address you can pass coordinates, with lat and lon, and the language can be it or en. The value is the one for the census section of the address, calculated with the same method as the liveability index page.

The API

The API is for anyone who wants to create reports and download the PDFs without going through the website: agency software that generates the report when a new listing comes in, a portal that attaches it to the property page. It is included in the Pro and Studio plans: request access in Settings, API, describing the intended use, and once confirmed you create access tokens, up to ten per account.

Every request goes to https://vicinalia.com/api/v1 with the headers Authorization: Bearer followed by the token, and Accept: application/json.

Reports created through the API count towards the plan just like those created on the site, and they appear in your account. Each token can make up to 60 requests a minute. The full guide, with sample responses, opens in Settings, API as soon as access is active.

For software developers

If you build property management software for agencies and want to bring the report to your clients, the link with the address and the partner code are enough to start: one button on the property record, nothing to connect. For a closer integration through the API, or to talk it over, write to us from the Contact page. What agencies expect from their software today is in the guide Real estate agency software in Italy, and what they find in the report is on the page for estate agents. Plans are on the Prices page.