Taxonomies

GET /api/taxonomies

Returns every codification accepted by the service, grouped by taxonomy. Read it to resolve the *_id fields of Create report and to label the ids coming back in the report blocks.

Example Request

curl --location 'https://insights.immobiliare.it/api/taxonomies' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>'

Request Fields

This endpoint takes no parameters.

Taxonomies in the response

Taxonomy	Entries	Used for	Where
`ASSET_GROUPS`	8	Macro group of the property type	`asset_group_id` on creation
`ASSET_TYPES`	33	Property type, scoped to a macro group	`asset_typology_id` on creation
`MAINTENANCE_STATUS`	4	Maintenance condition	`maintenance_status_id` on creation
`ENERGY_CLASSES`	16	Energy class	`energy_class_id` on creation
`SURFACE_TYPES`	29	Type of surface and its default commercial coefficients	`surfaces[].surface_type_id` on creation
`REPORT_TYPES`	2	Type of report to generate, `BASE` or `PRO`	`report_type_id` on creation
`HEATING_TYPES`	4	Type of heating	Codification of the property
`AGENT_JOB_TITLE`	2	Job title of the agent shown on the report	Agent fields on creation
`DEFAULT_COVER_IMAGES`	9	Cover images available for the report	Cover of the report
`REPORT_MODULS`	17	Pages the report is composed of, with their order	Layout of the report
`REPORT_STATUS`	3	Lifecycle status of a report, `BOZZA`, `ATTIVO`, `ARCHIVIATO`	Report management
`PUBBLICATION_STATUS`	3	Publication filter, `Pubblicati`, `Non Pubblicati`, `Tutti`	Report management
`MODULE_TYPES`	2	Products exposed by the platform, `REPORT_APPRAISAL`, `PROPERTY_VALUE`	Report management

Most taxonomies are lists of id and name pairs. Four of them carry extra keys:

ASSET_GROUPS: type classifies the group as RES (residential), COM (commercial) or DIR (offices).
ASSET_TYPES: asset_group_id links the type to its macro group. Filter on it to offer only the types belonging to the group the user picked.
SURFACE_TYPES: coefficient, until_mq and coefficient_over are the default commercial coefficients of that surface type, and list_typologies lists the asset_typology_id values it applies to.
REPORT_MODULS: uses codice, descrizione and ordine instead of id and name. ordine gives the position of the page in the report, descrizione is an internal label and is often an empty string.

Using SURFACE_TYPES on creation

The three coefficient keys map one to one onto the surfaces[] entries of Create report: read the defaults of the chosen surface_type_id and send them back, or override them with your own. When until_mq is set, coefficient applies up to that many square metres and coefficient_over applies beyond it. In the example below the garden counts for 15% up to 25 m² and 5% for the surface exceeding it.

Do not key on name, and do not sort by id

Two pitfalls in these lists:

name is not unique. SURFACE_TYPES contains two distinct entries both named Giardino, ids 10 and 14, with different coefficients. Always carry the id.
id is not ordinal. ENERGY_CLASSES returns A4 as id 15, A as 1, A+ as 2 and G as 8, so sorting by id scrambles the classes. The array is already in the intended display order: preserve it as returned.

Shape is not uniform across taxonomies

Three inconsistencies to allow for when parsing:

MODULE_TYPES is a list of plain strings, not of objects.
AGENT_JOB_TITLE returns id as a string ("1"), while ASSET_GROUPS, ENERGY_CLASSES and most others return it as a number (1). Compare loosely or normalise on read.
PUBBLICATION_STATUS is spelled with a double B. It is the key the API returns, so match it verbatim.

Cache the response

Taxonomies change rarely and the payload is around 10 KB. Fetch it once at startup, or on a slow refresh, rather than before every report creation. Never hardcode the ids: they are additive over time, and new values may appear without a change to the endpoint.

Example Response

Note

The longer lists are truncated in the example below, the actual response returns all the entries stated in the table above.

{
  "_metadata": {
    "message": "",
    "query": {},
    "status": 200
  },
  "data": {
    "AGENT_JOB_TITLE": [
      {
        "id": "1",
        "name": "Agente immobiliare"
      },
      {
        "id": "2",
        "name": "Consulente"
      }
    ],
    "ASSET_GROUPS": [
      {
        "id": 1,
        "name": "Appartamento",
        "type": "RES"
      },
      {
        "id": 2,
        "name": "Terracielo o terratetto",
        "type": "RES"
      }
    ],
    "ASSET_TYPES": [
      {
        "asset_group_id": 1,
        "id": 1,
        "name": "Appartamento"
      },
      {
        "asset_group_id": 1,
        "id": 2,
        "name": "Appartamento classe economica"
      }
    ],
    "DEFAULT_COVER_IMAGES": [
      {
        "id": 1,
        "url": "/report/appraisal/default-cover-image/1",
        "url_thumb": "/report/appraisal/default-cover-image/1?size=thumb"
      }
    ],
    "ENERGY_CLASSES": [
      {
        "id": 15,
        "name": "A4"
      },
      {
        "id": 14,
        "name": "A3"
      },
      {
        "id": 13,
        "name": "A2"
      }
    ],
    "HEATING_TYPES": [
      {
        "id": 1,
        "name": "Autonomo"
      },
      {
        "id": 2,
        "name": "Condominiale"
      },
      {
        "id": 3,
        "name": "Assente"
      },
      {
        "id": 4,
        "name": "Pompe di calore"
      }
    ],
    "MAINTENANCE_STATUS": [
      {
        "id": 1,
        "name": "Nuovo / In costruzione"
      },
      {
        "id": 2,
        "name": "Ottimo / ristrutturato"
      },
      {
        "id": 3,
        "name": "Buono / Abitabile"
      },
      {
        "id": 4,
        "name": "Da ristrutturare"
      }
    ],
    "MODULE_TYPES": [
      "REPORT_APPRAISAL",
      "PROPERTY_VALUE"
    ],
    "PUBBLICATION_STATUS": [
      {
        "id": 1,
        "name": "Pubblicati"
      },
      {
        "id": 2,
        "name": "Non Pubblicati"
      },
      {
        "id": 3,
        "name": "Tutti"
      }
    ],
    "REPORT_MODULS": [
      {
        "codice": "COPERTINA_B2C",
        "descrizione": "",
        "ordine": 1
      },
      {
        "codice": "CARATTERISTICHE_IMMOBILE_B2C",
        "descrizione": "PageCaratteristicheImmobileB2C",
        "ordine": 2
      }
    ],
    "REPORT_STATUS": [
      {
        "id": 1,
        "name": "BOZZA"
      },
      {
        "id": 2,
        "name": "ATTIVO"
      },
      {
        "id": 3,
        "name": "ARCHIVIATO"
      }
    ],
    "REPORT_TYPES": [
      {
        "id": 1,
        "name": "BASE"
      },
      {
        "id": 2,
        "name": "PRO"
      }
    ],
    "SURFACE_TYPES": [
      {
        "coefficient": 100.0,
        "coefficient_over": null,
        "id": 1,
        "list_typologies": [
          6,
          7,
          10,
          11
        ],
        "name": "Abitazione",
        "until_mq": null
      },
      {
        "coefficient": 15.0,
        "coefficient_over": 5.0,
        "id": 10,
        "list_typologies": [
          1,
          2,
          3,
          4
        ],
        "name": "Giardino",
        "until_mq": 25.0
      }
    ]
  }
}

Names are in Italian

Every name is a display label in Italian and is meant to be shown as it is. If your integration is localised, map the ids to your own labels rather than translating these strings at runtime.