Core concepts

This page explains the objects the API returns and how they relate. The reference lists every field.

The data model

Organization                 your company in Telescope; an API key sees only this
└── Portfolio                a folder of properties; portfolios can be nested
    ├── Portfolio            child portfolio
    └── Property             a real estate asset on a plot of land
        ├── hazards[]        climate hazard results, one per hazard
        ├── biodiversity[]   biodiversity results, one per analysis
        ├── buildings[]      buildings on the plot, from the national register
        └── energy_certificates[]   energy performance certificates

Organization

The company or team that owns the data. You never pass an organization ID. The API key decides it.

Portfolio

A named group of properties, such as a fund, a region or a client. Portfolios form a tree: a root portfolio can contain child portfolios, which can contain their own, and so on. Every property sits directly in exactly one portfolio.

You create and arrange portfolios in the Telescope app. The API lists them so you can group your properties the same way. See Portfolios.

Property

A real estate asset: a plot of land with an address, and usually one or more buildings. Telescope runs its analyses on the plot's geometry. The API returns a property's address, identifiers and value, plus its results in four lists:

List	What it holds
hazards	How exposed the property is to each climate hazard, such as landslides or surface flooding
biodiversity	Whether the property overlaps or is near sensitive nature, such as protected areas
buildings	Buildings registered on the plot, with usage, construction year, area and floors
energy_certificates	Energy labels issued for the property, newest first

Analyses and stored results

When a property is added, or its plot changes, Telescope runs its analyses in the background and stores the results. The API returns these stored results. Reading a property never starts a new analysis.

This has two consequences for integrations:

• New properties start empty. Right after a property is created, hazards and biodiversity are empty lists. They fill in as the analyses finish.
• A missing entry means no stored result. If a hazard isn't in hazards, Telescope has no result for it yet. That is different from an entry with exposure NOT_EXPOSED, which means it was analyzed and the property isn't exposed.

Understanding a hazard result

Each entry in hazards describes one climate hazard for one property.

Field	Meaning
name	The hazard, such as landslide. See hazards.
exposure	How exposed the location is: from NOT_EXPOSED through VERY_LOW up to VERY_HIGH.
relevant	Whether the hazard matters for this property.
sensitivity	How sensitive the property is to the hazard, if someone has assessed it.
vulnerability	The combined result of exposure and sensitivity.

Exposure comes from Telescope's analysis of the location under several climate scenarios. The API gives you the single level Telescope uses: the highest level across the scenarios, unless a user has overridden it in the app.

Relevance is set by the analysis first. Users can change it, for example when a hazard can't affect the property's buildings. A hazard can have a high exposure and still be marked not relevant. Most reports should only count relevant hazards.

Sensitivity is assessed by users in Telescope. Until someone does, it is null, and so is vulnerability.

Vulnerability is calculated from exposure and sensitivity, so a user's exposure override changes it too. Users can't override vulnerability itself.

Understanding a biodiversity result

Each entry in biodiversity describes one biodiversity analysis, such as protected_areas or red_list_species.

Field	Meaning
name	The analysis. See biodiversity analyses.
relevant	Whether the topic matters for this property. A user's override if set, otherwise the analysis result.
proximity	overlaps if the property overlaps the analyzed features, nearby if it is close, null otherwise.

Identifiers

Field	What it is	Who sets it
id	Telescope's identifier, a UUID. Stable for the lifetime of the object.	Telescope
internal_reference_id	Your own identifier, such as the property ID in your ERP or property register. Can be empty.	You
matrikkelnummer	The Norwegian cadastral identifier of the plot, like 0301-208/101/0/0.	Set when the property is added, and can be changed when you update it

Use id as the primary key when you store Telescope data. Use internal_reference_id to join Telescope data with your own systems, and to create or update properties without making duplicates.

A matrikkelnummer reads as municipality number, then gårdsnummer (gnr), bruksnummer (bnr), festenummer (fnr) and seksjonsnummer (snr): 0301-208/101/0/0 is municipality 0301 (Oslo), gnr 208, bnr 101, fnr 0, snr 0.

Timestamps

All timestamps are ISO 8601 in UTC, like 2026-09-30T12:01:44.104221Z.

• A property's updated_at changes when the property itself changes, such as its name, address or portfolio.
• It does not change when its hazard or biodiversity results, buildings or energy certificates change. Each hazard and biodiversity result has its own updated_at.

Sync data explains how to keep results current.