Skip to content

Getting started

Welcome to the Comps API documentation. Use the left navigation to browse endpoints and guides.

Environments

https://comparables.realitycs.it

https://sandbox-comparables.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 finds comparables, that is properties similar to the one you are analysing, and returns their details. The usual flow is a search that returns a page of results, followed by a detail call on the ones you care about.

  1. Search, either by attribute starting from filters, or by property starting from a property you describe.
  2. Take the uuid of a result from the response.
  3. Read the Comparable Detail, or the Comparable Project when the result is a project.
  4. Optionally render the detail as a PDF.
Endpoint Use it to
Search by Attribute Search by filters, returns a paginated list of summaries
Full Search by Attribute Same search, but with the full detail of every result inline
Search by Property Search starting from the description of a property
Comparable Detail Read one comparable, by uuid or by listing id
Comparable Project Read one project, by uuid
Comparable Detail pdf Render the detail of a comparable as a PDF

When to use Full Search by Attribute

Full Search by Attribute is the union of the search and the detail call, so it saves you a round trip per result. It is available for Asking data only, not for Sales data: for sale comparables you have to go through the search plus Comparable Detail. See Mapping of output data for which fields each route returns.

Request format

Searches are POST calls taking a JSON body, detail calls are GET with the identifier in the path:

Content-Type: application/json

Search bodies are structured in three blocks:

  • Filters: the search criteria. Unused criteria can be left as null rather than omitted.
  • Pagination: page and limit.
  • Sorting: by and direction.

Choosing the search area

The area is expressed by one of the mutually alternative filters marketZoneID, omiZoneID, municipalityID or boundingBox. The ids come from the location taxonomies: market zone, OMI zone, municipality, province and region.

Codified fields

Every *ID filter is codified. Taxonomies General lists the value sets for comparableType, contractType, categoryType, propertyType, maintenanceStatus, clientType and the others, while the location ones are covered by Taxonomies Location.

Sale comparables need to be enabled on your account

comparableTypeID selects what you are searching for, and not every value is accessible by default. Offerta and Stima are generally available, while the Compravendita types, that is the actual closed transactions, have to be enabled by the Sales team, and Compravendita approssimata requires a further specific request on top of that.

If a search returns nothing for a Compravendita type, check your entitlements before assuming there is no data in the area.

Response format

Searches answer with the standard Insights envelope: _metadata with the outcome and the pagination, items with the results.

_metadata carries more than the status:

  • page, limit, total_count and pages with first, last, next, previous and self, to drive the pagination. next and previous are null at the ends.
  • query: the filters as they were actually interpreted, with the codified ids resolved into their labels. Useful to confirm the search you ran is the search you meant.
  • request_id and map: identifier of the search and a ready made URL rendering its results on a map.

Not every field is always populated

Only the fields marked with an asterisk in Mapping of output data are guaranteed. Everything else is null when the information is not available for that comparable, so treat missing values as normal rather than exceptional.

Changes

All updates to the endpoints are tracked in the Changelog.