---
title: "One building"
method: GET
path: "/buildings/{building_id}"
tags: ["Buildings"]
---

# One building

`GET /buildings/{building_id}`

## Request

- Base URL: `https://api.baseray.ai/v1`
- URL: `https://api.baseray.ai/v1/buildings/{building_id}`
- Auth: HTTP bearer

One building's whole record, as the baseray app's building panel shows it: the building itself, its addresses (each entrance with the dwellings behind it), what its register record says of its units floor by floor and kind by kind, the whole record as its register lays it out, the roof analysis plane by plane, the local climate with its heating degree-days and warming trend, gas and district-heating network evidence, and the heating estimate. A building the catalogue no longer holds is still returned with `is_current` false and, where one now stands on its ground, `replaced_by_building_id`.

## Path parameters

- `building_id` string, uuid, required

## Response `200`

OK

- BuildingDetailEnvelope
  - `data` BuildingDetail, required
    - `building_id` string, uuid, required: The building's baseray id.
    - `address` string, nullable, required: The building's address as a record states it (`address_evidence` says which kind): street and house number, a Romanian village's `nr. 350` where the record names no street, or a Czech municipality and number (`Lhota 25`), with the block where one is given. Null when no address of the building is on record; the nearest named road is then `nearest_road`, never this.
    - `nearest_road` string, nullable, required: The named road nearest the building, given only where no address of it is on record (`address` is then null). It helps find the building but is not its address: no house number is known.
    - `address_evidence` 'address_record' | 'business_listing' | 'null', nullable, required: What kind of record `address` comes from: `address_record` (an address record of the building) or `business_listing` (a listing of a business at the building, not an address record of it). Null when `address` is null or the kind is unknown.
    - `address_corroboration` 'corroborated' | 'single_source' | 'conflicting' | 'null', nullable, required: How other records back the house number of `address`, as the `address_corroboration` filter reads it: `corroborated` (an independent record gives the same number), `single_source` (only one record) or `conflicting` (another record gives another number). Null without a house number.
    - `postal_code` string, nullable, required: The official postcode of the building's address; null when none is on record.
    - `locality` string, nullable, required: Town, city or village.
    - `country` string, nullable, required: ISO 3166-1 alpha-2 country code.
    - `latitude` number, required: Latitude of the building's centre, WGS84.
    - `longitude` number, required: Longitude of the building's centre, WGS84.
    - `category` 'residential_house' | 'apartment_block' | 'commercial' | 'industrial' | 'public' | 'agricultural' | 'ancillary' | 'unknown', required: Building category; `ancillary` is an annex or outbuilding.
    - `category_evidence` 'confirmed' | 'corroborated' | 'inferred' | 'conflicting' | 'unconfirmed', required: How firmly `category` is known: `confirmed` (an official register states it), `corroborated` (several sources agree), `inferred`, `conflicting` (sources disagree) or `unconfirmed` (always so for `unknown`).
    - `building_type` string, nullable, required: The building's granular type where a record states one, as the `building_type` filter reads it, e.g. `office`, `warehouse`, `school`, `apartments`; null when none is stated.
    - `roof_shape` string, nullable, required: The roof's shape, as the `roof_shape` filter reads it, e.g. `gabled`, `hipped`, `flat`; null when unknown.
    - `footprint_area_m2` number, required: Ground footprint, in m².
    - `height` Height, required
      - `metres` number, required: Height in metres.
      - `basis` 'measured' | 'stated' | 'estimated', required: `measured` (the building itself was measured), `stated` (a record gives it: an official building catalogue, crowd mapping or the dataset of the building's outline) or `estimated` (modelled).
    - `volume_m3` number, nullable, required: Volume, in m³; null when unknown.
    - `volume_basis` 'measured' | 'estimated' | 'null', nullable, required: Whether the volume is measured or estimated; null with the volume.
    - `floor_area` FloorArea, required: The building's floor area as best known: the figure a record states for the building where one holds, otherwise an estimate.
      - `square_metres` number, required: Floor area, in m².
      - `basis` 'measured' | 'stated' | 'estimated' | 'null', nullable, required: `stated` (a record states it for the building) or `estimated` (modelled: the footprint, or a record's built area, times the floors); null when unknown.
      - `scope` 'gross_whole_building' | 'net_whole_building' | 'gross_full_storeys' | 'gross_above_ground' | 'null', nullable, required: What the figure counts: `gross_whole_building` (every storey, walls included), `net_whole_building` (the usable area of every storey, walls excluded), `gross_full_storeys` (the ground floor and every full storey, walls included; the basement and the attic are not counted) or `gross_above_ground` (the footprint times the floors above ground, walls included); null when unknown.
    - `floors` integer, nullable, required: Floors above ground; null when unknown.
    - `floors_including_underground` integer, nullable, required: Only where `floors` is unknown: the floors above and below ground counted together, as a building register states them (Czechia's counts them so, a habitable attic as one). How many of them are above ground is not on record. Null otherwise.
    - `construction_year` integer, nullable, required: The year a register states the building was completed; null when none states it.
    - `completed_by_year` integer, nullable, required: Where a register dates the building only by a census period: the last year of that period, the year it stood by. Null otherwise.
    - `dwellings` integer, nullable, required: Dwellings, where known; null when unknown.
    - `existing_solar_panels` ExistingSolarPanels, required: Whether solar panels are already on the roof, as a dated photo of the roof shows it. This is the photo alone: `solar_presence` settles it with the registers of connected installations, which outrank a photo.
      - `status` 'detected' | 'none_seen' | 'unclear' | 'not_checked', required: `detected`, `none_seen`, `unclear`, or `not_checked` (never checked, or the photo was too coarse to check).
      - `photo_date` string, date, nullable, required: Date of the photo checked; null when undated or never checked.
      - `confidence` number, nullable, required: The check's confidence in its result, 0 to 1; null when not checked.
      - `analysed_on` string, date, nullable, required: The day the photo was checked for panels; null when never checked.
      - `photo_resolution_cm` number, nullable, required: How fine the photo is, in centimetres per pixel; a photo too coarse to check is why a roof stays `not_checked`. Null when not known.
    - `solar_presence` 'registered' | 'detected' | 'registered_at_address' | 'none_seen' | 'unclear' | 'unknown', required: Whether the building carries solar panels, settled across the official registers of connected solar installations and the roof photo of `existing_solar_panels`. A register entry is the stronger evidence: a photo may predate an installation or miss it. `registered`: a register states an installation at the building's address, and the building alone holds that address or its own photo shows the panels. `detected`: panels are seen in the photo and no register states an installation. `registered_at_address`: a register states an installation at an address this building shares with others (`registered_solar.address_building_count` of them) and its photo shows none, so the register does not say which roof carries the panels: not a plain yes. `none_seen`: a photo detailed enough shows no panels and no register states an installation. `unclear`: the photo is unclear and no register states one. `unknown`: neither says. A building no register names is never thereby without solar: an installation may be off the grid, or registered under an address written otherwise. The `solar_presence` and `exclude_solar_presence` filters of `GET /buildings` read this field.
    - `registered_solar` RegisteredSolar, required: The solar installations official registers state at the building's address: grid operators' lists of connected installations, energy regulators' generation licences and building registers' installations (`kinds` says which). A register names a site by its address or its building, never a roof, a person or a metering point.
      - `installation_count` integer, required: Installations registered at the address.
      - `installed_power_kw` number, nullable, required: Installed power in kW: the installations' sum where every one states its own, null otherwise, never a partial sum.
      - `export_power_kw` number, nullable, required: Power approved to feed the grid, in kW: the installations' sum where every one states its own, null otherwise.
      - `storage_capacity_kwh` number, nullable, required: Energy storage in kWh: the sum where every installation that stores states its capacity, null otherwise; often null even where `has_storage` is true.
      - `has_storage` boolean, nullable, required: True where an installation is stated to store energy, false where every installation is stated to store none, null where the register does not say. A register of generation licences does not record storage.
      - `first_connected_on` string, date, nullable, required: The earliest date the installations state; null when not stated, or when a register states only the year (`establishment_year`), which is then given as `first_connected_year` alone. What it dates is in `kinds`: a connection certificate for `grid_connection`, the start of the current holder's licence for `generation_licence`, when the plant may be older.
      - `latest_connected_on` string, date, nullable, required: The latest date the installations state, of the same meaning as `first_connected_on`, and the same date for a single installation.
      - `first_connected_year` integer, nullable, required: The year of the earliest date the installations state, given whenever a date is. Where a register states only the year (`establishment_year` in `kinds`) it is the only date given: `first_connected_on` and `latest_connected_on` are then null. Null when nothing is stated.
      - `latest_connected_year` integer, nullable, required: The year of the latest date the installations state, of the same meaning as `first_connected_year`, and the same year for a single installation.
      - `address_building_count` integer, required: Buildings holding the address the register names, this one included. Of several installations it is the fewest: one at an address the building alone holds is its own.
      - `shares_address` boolean, required: True when `address_building_count` is above 1: the register then does not say which of the buildings carries the panels.
      - `kinds` string[], required: What the registers record, which says what the dates mean. `grid_connection`: a grid operator's list of connected installations, dated by the connection certificate. `generation_licence`: a regulator's generation licences, dated by the start of the current holder's licence, so the plant may be older and the date is never when it was installed. `establishment_year`: a building register's installations, dated by the year the installation was established as an owner or a municipality states it, never by its connection; only the year is stated, so the dates are null and only `first_connected_year` and `latest_connected_year` are given. Usually one kind; empty only when the kind could not be read.
      - `reported_through` string, date, required: The last day of the latest month the registers report: an installation entered after it is not yet listed.
    - `solar_potential` SolarPotential, required: Rooftop solar potential, present only where the roof has been modelled.
      - `max_panel_count` integer, nullable, required: Solar panels that fit on the roof.
      - `max_capacity_kwp` number, nullable, required: Capacity of those panels, in kWp.
      - `yearly_energy_kwh` number, nullable, required: Energy they would produce in a year, in kWh.
      - `usable_roof_area_m2` number, nullable, required: Roof area usable for panels, in m².
      - `co2_savings_kg_per_year` number, nullable, required: CO₂ the installation would save, in kg a year.
      - `basis` 'measured' | 'measured_cut_to_outline' | 'estimated' | 'null', nullable, required: `measured` where the figures come from the roof itself as measured: a surface model read over it, or roof planes an open survey measured on the building (`roof_analysis.roof_survey` says how). `measured_cut_to_outline` where the measured roof took in the roofs attached to the building (a terraced or semi-detached house) and was cut to the building's outline: its planes and panels were measured, but each is kept or dropped whole by where its centre lies, so the figures approximate the building's own part. `estimated` where they are modelled from the footprint and sunshine. Null when not said.
    - `registered_business_count` integer, required: Active businesses whose registered office is the building's address. Never ownership or occupancy.
    - `registered_business_employees` string, nullable, required: The largest stated size of a business registered at the address, as the `registered_business_employees` sort and filters read it: an exact count (`12`), a band (`10–49`) or an open top band (`1000 or more`); null when none is stated.
    - `registered_business_turnover` Turnover, required: A turnover from a business's latest financial statement on record.
      - `amount` integer, required: Turnover, in whole units of `currency`.
      - `currency` string, nullable, required: ISO 4217 currency of the statement.
      - `financial_year` integer, nullable, required: The financial year of the statement.
    - `flood_zone` '5_year' | '10_year' | '20_year' | '50_year' | '100_year' | '100_year_climate_change' | '500_year' | '1000_year' | '10000_year' | 'null', nullable, required: The most frequently flooded zone of an official flood hazard map the building lies in, named by the return period of its flood; `100_year_climate_change` is the 1-in-100-year flood under the climate the map projects. Null means outside every zone only where `flood_zone_mapped` is true; elsewhere the zone is unknown.
    - `flood_zone_mapped` boolean, required: True where a served flood hazard map covers the building. Flood maps are served only where their licence allows it; where none covers the building this is false and its flood zone is unknown, never "no flood risk".
    - `flood_zone_source` string, nullable, required: The credit and the reading the flood map's publisher requires wherever its zone is shown, such as Denmark's "Kilde: Kystdirektoratet, Kystplanlægger.dk" with its note that the zone is a screening, never an assessment of the property. Null where no served map covers the building, or its publisher requires none.
    - `seismic_design_acceleration_g` number, nullable, required: The design peak ground acceleration of the building's site, in g, as the national seismic design code maps it (P100-1/2013 in Romania); null when unknown.
    - `seismic_risk_class` 'RsI' | 'RsII' | 'RsIII' | 'RsIV' | 'U1' | 'U2' | 'U3' | 'consolidated' | 'null', nullable, required: The seismic risk class an official list of technically assessed buildings gives the building: `RsI` (the highest risk) to `RsIV`, the urgency classes `U1` (the most urgent) to `U3` older assessments set, or `consolidated` (strengthened since). Null when the building is on no such list, which says nothing of its risk.
    - `seismic_risk_assessment_year` integer, nullable, required: The year of the assessment that set `seismic_risk_class`; null when not stated.
    - `app_url` string, uri, required: The building in the baseray app.
    - `entrances` integer, nullable, required: Entrances: each listed address of the building counts as one; null when none are listed.
    - `stated_facts` StatedFact[], required: Everything the building's record states, as it words it; empty when no record is on file. A floor area here is the record's own figure; the building's floor area is `floor_area`.
      - `fact` string, required: What the fact is, e.g. `use`, `construction_year`, `completed_by_year` (the year a building stood by, where it is dated only by a period ending then), `floors_above_ground`, `floors_below_ground`, `built_up_area`, `floor_area`, `enclosed_volume`, `dwelling_count`, `unit_count`, `heating` or `cadastral_number`. New kinds of fact may appear; treat an unknown one by its `label`.
      - `label` string, required: The fact's name, for people.
      - `value` union, required: A number (a count, a year, or a quantity in `unit`), the record's wording, or its wordings.
        - string
        - number
        - string[]
      - `unit` string, nullable, required: The unit of a quantity: `m2` or `m3`; null for counts, years and wordings.
      - `note` string, nullable, required: How the record defines or qualifies the value; null when it adds nothing.
    - `is_current` boolean, required: False once the building is no longer in the catalogue's current release.
    - `replaced_by_building_id` string, uuid, nullable, required: The building now standing on a retired building's ground, when there is one.
    - `outline_reference` 'footprint' | 'roof_edge' | 'combined' | 'null', nullable, required: What the building's outline, and so `footprint_area_m2`, traces where the building is drawn from parts: `footprint` (the walls where they meet the ground), `roof_edge` (the roof seen from above, eaves included) or `combined` (parts of both kinds); null where it is not drawn from parts.
    - `parts` BuildingPart[], required: The parts the building is drawn from, register parts first, then the largest; empty where it is not drawn from parts.
      - `origin` 'register' | 'unregistered', required: `register` (a construction the building register records) or `unregistered` (a structure the register does not record; this says nothing of whether it is permitted).
      - `record_reference` string, nullable, required: The register's own reference for the construction's record; null for a part not in the register.
      - `label` string, nullable, required: How the register names the construction, e.g. `62847-C1`; null where it names none.
      - `outline_reference` 'footprint' | 'roof_edge', required: What the part's outline traces: `footprint` (the walls where they meet the ground, as the register surveys them) or `roof_edge` (the roof seen from above, eaves included).
      - `area_m2` number, required: The area of the part's outline, in m².
    - `eave_height_m` number, nullable, required: The height of the eaves; null when unknown.
    - `has_3d_model` boolean, nullable, required: Whether a 3D model of the building's roof is on record, reconstructed from a surface model of the roof or from the analysed roof planes; it does not say which. Null when unknown.
    - `addresses` BuildingAddresses, required: Every address of the building, the shown one first, and whether its records agree on the shown number.
      - `confirmation` 'confirmed' | 'records_disagree' | 'single_record' | 'null', nullable, required: `confirmed` (several records give the shown street the same number), `records_disagree` (they give it different numbers) or `single_record`; null when no number was compared.
      - `addresses` BuildingAddress[], required: Every address, the shown one first.
        - `line` string, required: The address written the country's way: street and number, then the block (`bl.`) and entrance (`sc.`) where given.
        - `postal_code` string, nullable, required: The address's official postcode where one is known, else the one its record writes; null when none is.
        - `locality` string, nullable, required: The town or village.
        - `entrance` string, nullable, required: The entrance the address names; null for an address that names none.
        - `dwellings_at_entrance` integer, nullable, required: The dwellings counted behind this entrance, never the building's total; null for an address that is no entrance or whose dwellings are not counted.
        - `relation` 'shown' | 'same_address' | 'different_number' | 'other_street' | 'another_entrance' | 'null', nullable, required: `shown` (the address the building is shown with), `same_address` (another record gives the shown street the same number), `different_number` (another record gives the shown street a different number), `other_street` (the building's front on another street), `another_entrance` (another entrance or number of the building); null when not compared.
    - `units` UnitsSummary, required: What the building's record says of its units: the units and dwellings it lists, floor by floor and kind by kind, against the totals it states of itself, and the dwellings it counts behind each entrance. The units themselves are read with `GET /buildings/{building_id}/units`.
      - `listed` integer, nullable, required: The units the record lists; null when it lists none, which says nothing of how many there are.
      - `listed_dwellings` integer, nullable, required: The dwellings among the listed units; null when none are listed.
      - `stated` integer, nullable, required: The units the record states the building has; null when it states no total.
      - `stated_dwellings` integer, nullable, required: The dwellings the record states the building has; null when it states no total.
      - `list_is_complete` boolean, required: True when the record lists units and its list matches every total it states: a unit missing from an incomplete list may still exist.
      - `by_floor` FloorUnits[], nullable, required: The listed units on each floor, bottom to top; a unit whose floor is not known is on none. Null when no units are listed, never to be read as none.
        - `floor_kind` 'basement' | 'semi_basement' | 'ground' | 'upper' | 'attic', required: Which kind of floor: `basement`, `semi_basement`, `ground`, `upper` or `attic`.
        - `floor_number` integer, nullable, required: Basements and upper floors only, counted from 1; null for the others.
        - `units` integer, required: The listed units of every kind on the floor.
        - `dwellings` integer, required: The listed dwellings among them.
      - `by_kind` UnitKindCount[], nullable, required: The listed units of each kind, kinds the list holds none of left out. Null when no units are listed.
        - `kind` 'dwelling' | 'commercial' | 'parking' | 'storage' | 'other', required: `dwelling`, `commercial` (a shop, an office or other business premises), `parking`, `storage` or `other`; a unit the record gives no kind is `other`.
        - `units` integer, required: The listed units of that kind.
      - `entrances` string[], required: The entrances the listed units are reached by, as the record names them, in reading order.
      - `entrance_dwellings` EntranceDwellings[], required: The dwellings the record counts behind each entrance; empty when it counts none.
        - `entrance` string, required: The entrance, by its address as the record writes it.
        - `dwellings` integer, required: The dwellings counted behind it.
    - `record_sheet` RecordSheet, required: The building's whole record as its register lays it out: its identity numbers, then every fact it states, by section (such as use, areas, storeys, construction, heating and utilities, energy certificate, accessibility). The facts are the record's own, as it words them.
      - `exists` boolean, nullable, required: False when the record says the building no longer stands; null where the register keeps no such mark.
      - `validated` boolean, nullable, required: Whether the register marks the record checked; null where it keeps no such mark.
      - `cadastral_number` string, nullable, required: The building's cadastral number, where the record keeps one.
      - `property_number` string, nullable, required: The property number, where the record keeps one.
      - `land_book_number` string, nullable, required: The land book number, where the record keeps one.
      - `read_on` string, date, nullable, required: The day the record was last read.
      - `sections` RecordSheetSection[], required: Every fact on record, by section; empty when the record states none beyond its numbers.
        - `title` string, required: The section's title.
        - `rows` RecordSheetRow[], required: The facts in the section.
          - `label` string, required: The fact's name, or a list entry's own wording.
          - `value` union, required: The value as the record states it: a wording, a number in `unit`, or a yes or no.
            - string
            - number
            - boolean
          - `unit` string, nullable, required: The unit of a quantity as written, e.g. `m2`, `W/m2K`, `kWh/m2/year`; null for wordings and counts.
    - `roof_analysis` RoofAnalysis, required: The roof analysis behind the building's solar potential (`solar_potential`): the roof's areas and sunshine, the photo it was read from, the panel its layout assumes and the roof plane by plane. Where `planes_are_assumed` is true the planes are an estimate's assumption, not a measurement.
      - `whole_roof_area_m2` number, nullable, required: The whole roof's area.
      - `ground_area_m2` number, nullable, required: The ground the analysed roof covers.
      - `peak_sunshine_hours_per_year` number, nullable, required: Peak sunshine hours a year at the roof.
      - `yearly_irradiance_kwh_per_m2` number, nullable, required: The solar energy a square metre of the roof receives in a year.
      - `imagery_date` string, date, nullable, required: The date of the imagery the roof was read from; null when undated or assumed.
      - `imagery_quality` string, nullable, required: The imagery's quality as the analysis grades it.
      - `confidence` number, nullable, required: The analysis's confidence, 0 to 1.
      - `planes_are_assumed` boolean, nullable, required: True where the planes are an estimate's assumption, false where they were measured, null where unsaid.
      - `roof_survey` 'lidar' | 'image_matching' | 'null', nullable, required: Where the planes were measured on the building by an open survey: how it measured them, `lidar` (airborne laser scanning) or `image_matching` (a point cloud matched from overlapping aerial photographs, which is not lidar). Null where the planes come from no such survey (read from imagery, or assumed) or from a survey baseray does not list.
      - `panel_capacity_w` number, nullable, required: The power of the panel the layout assumes.
      - `panel_width_m` number, nullable, required: The width of that panel.
      - `panel_height_m` number, nullable, required: The height of that panel.
      - `planes` RoofPlane[], required: Every plane of the roof, by its number.
        - `plane` integer, required: The number the analysis gives the plane.
        - `facing` 'north' | 'north-east' | 'east' | 'south-east' | 'south' | 'south-west' | 'west' | 'north-west', required: The compass direction the plane faces.
        - `azimuth_degrees` number, required: The bearing the plane faces: 0 north, 90 east, 180 south.
        - `pitch_degrees` number, required: The plane's slope from the horizontal.
        - `area_m2` number, required: The plane's area.
        - `sunshine_hours_per_year` number, nullable, required: The sunshine the plane gets in a year; null when not analysed.
        - `panels` integer, required: Panels the largest layout puts on the plane.
    - `climate` Climate, required: The local climate at the building, from gridded climate data for its location, never an on-site measurement.
      - `periods` ClimatePeriod[], required: The temperatures, frost and hot days and rainfall per period; a period with no figure on record is left out.
        - `period` 'latest_year' | 'recent_average' | 'current_year', required: `latest_year` (the last complete year), `recent_average` (yearly average over the recent years) or `current_year` (this year so far, preliminary).
        - `from` string, nullable, required: Where the period starts: a year, or a date for `current_year`.
        - `to` string, nullable, required: Where the period ends: a year, or a date for `current_year`.
        - `data_through` string, date, nullable, required: The last day the data covers.
        - `coldest_day_c` number, nullable, required: The lowest daily temperature, °C.
        - `hottest_day_c` number, nullable, required: The highest daily temperature, °C.
        - `frost_days` number, nullable, required: Days below freezing.
        - `hot_days` number, nullable, required: Hot days.
        - `precipitation_mm` number, nullable, required: Rainfall over the year, mm.
        - `wet_days` number, nullable, required: Wet days.
        - `wettest_day_mm` number, nullable, required: Rainfall on the wettest day, mm.
      - `heating_degree_days` HeatingDegreeDays[], required: The heating degree-days per period, the climate normal first; a period not on record is left out.
        - `period` 'standard_normal' | 'recent_average' | 'latest_year', required: `standard_normal` (the climate normal), `recent_average` (yearly average over the recent years) or `latest_year` (the last complete year).
        - `from` string, required: The first year of the period.
        - `to` string, required: The last year of the period.
        - `degree_days` number, required: Heating degree-days, K·d.
      - `temperature_trend_c_per_decade` number, nullable, required: How fast the location has warmed, °C per decade; null where the trend is not on record or has no clear direction.
    - `energy_networks` EnergyNetworkLevel[], required: Gas and district-heating network evidence from the locality down to the building; empty when none is on record.
      - `network` 'natural_gas' | 'district_heating', required: The network.
      - `level` 'locality' | 'service_area' | 'street' | 'address' | 'building', required: How close to the building the evidence reaches: the locality, the service area, the street, the address or the building's own connection.
      - `present` boolean, required: Whether the network is on record at that level.
      - `year` integer, nullable, required: The year the evidence refers to.
    - `heating_estimate` HeatingEstimate, required: The building's heating estimate. Every figure is a model estimate, never a metered value, an energy certificate or a sizing.
      - `useful_heat_kwh_per_year` number, nullable, required: The headline: the heat the building needs in a year for space heating, as it was built (insulated or re-glazed since, it needs less).
      - `useful_heat_low_kwh_per_year` number, nullable, required: Where the number of floors is not on record: the lowest need over the floor counts the building may have.
      - `useful_heat_high_kwh_per_year` number, nullable, required: Where the number of floors is not on record: the highest need over the floor counts the building may have.
      - `useful_heat_kwh_per_m2_per_year` number, nullable, required: The heat need per m² of heated floor area.
      - `heated_floor_area_m2` number, nullable, required: The heated floor area the need is worked out on.
      - `heated_floor_area_basis` string, nullable, required: What the heated floor area rests on, e.g. `register_heated_area` or `volume_share`.
      - `useful_heat_kwh_per_dwelling_per_year` number, nullable, required: The heat need of one dwelling on average, where the dwellings are counted.
      - `dwelling_count` integer, nullable, required: The dwellings that figure is per.
      - `delivered_energy_kwh_per_year` number, nullable, required: The energy delivered to the heating system for that need.
      - `expected_energy_kwh_per_year` number, nullable, required: The energy the building is expected to use for heating.
      - `peak_heat_load_kw` number, nullable, required: The peak heat load.
      - `peak_heat_load_basis` string, nullable, required: What the peak heat load rests on; `screening_estimate` is an order of magnitude at the standard winter design temperature of the location.
      - `design_outdoor_temperature_c` number, nullable, required: The outdoor temperature the peak heat load is worked out at, °C.
      - `hot_water_heat_kwh_per_year` number, nullable, required: The heat in the hot water, apart from space heating and in none of the other figures.
      - `hot_water_persons` number, nullable, required: The people the hot water is worked out for.
      - `hot_water_occupancy_basis` string, nullable, required: Where those people come from: `counted_dwellings`, `one_household` or `heated_floor_area`.
      - `construction_period_is_on_record` boolean, nullable, required: False when the construction period behind the estimate is assumed, not read from the building's own record.
      - `era_scenarios` HeatingEraScenario[], required: Where the construction year is not on record: the need under each construction period.
        - `first_year` integer, nullable, required: The period's first year; null for the earliest.
        - `last_year` integer, nullable, required: The period's last year; null for the latest.
        - `useful_heat_kwh_per_year` number, required: The heat need under that period.
        - `is_taken` boolean, required: Whether the other figures assume this period.
      - `neighbours_are_measured` boolean, nullable, required: False when the neighbouring buildings were not measured and every wall was taken to face the weather.
      - `neighbour_wall_share` number, nullable, required: The share of the walls, 0 to 1, standing against neighbouring buildings; null where they were not measured.
      - `heat_pump_scenarios` HeatPumpScenario[], required: The electricity a heat pump would use per seasonal performance factor.
        - `seasonal_performance_factor` number, required: The seasonal performance factor assumed.
        - `electricity_kwh_per_year` number, nullable, required: The electricity a year.

## Other responses

- `400`: A parameter is missing, malformed or out of range (`invalid_parameter`).
- `401`: No API key, or one that does not work: `missing_api_key`, `invalid_api_key`, `revoked_api_key` or `expired_api_key`.
- `402`: `insufficient_credits`: the answer's buildings need more credits than the workspace has left this month. Nothing was returned or charged.
- `403`: The key may not do this: `insufficient_scope`, or `workspace_access_revoked` when the key's creator no longer belongs to its workspace.
- `404`: No building has this id (`not_found`).
- `429`: `rate_limited` (the key's per-minute limit) or `quota_exceeded` (the workspace's daily quota).
- `503`: The building catalogue is unavailable right now (`upstream_unavailable`); retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/baseray/apis/baseray-api.md) · [All operations](https://skmtc.dev/baseray/apis/baseray-api/llms.txt) · [OpenAPI document](https://skmtc.dev/baseray/apis/baseray-api/revisions/2dc2808717f7?raw)