---
title: "Buildings in an area, ranked"
method: GET
path: "/buildings"
tags: ["Buildings"]
---

# Buildings in an area, ranked

`GET /buildings`

## Request

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

One ranked page of the buildings inside `bbox` that pass every filter given. Filters of different names combine with AND; the values of one list filter combine with OR. An area outside the countries baseray covers answers with no buildings; https://baseray.ai/countries lists them and takes requests for others.

## Query parameters

- `bbox` string, required
- `sort` 'volume' | 'area' | 'height' | 'registered_business_turnover' | 'registered_business_employees'
- `limit` integer
- `offset` integer
- `category` string[]
- `building_type` string[]
- `roof_shape` string[]
- `min_floors` integer
- `max_floors` integer
- `min_dwellings` integer
- `max_dwellings` integer
- `min_entrances` integer
- `max_entrances` integer
- `address_corroboration` string[]
- `min_area_m2` number
- `max_area_m2` number
- `min_height_m` number
- `max_height_m` number
- `min_volume_m3` number
- `max_volume_m3` number
- `measured_height_only` boolean
- `solar_presence` string[]
- `exclude_solar_presence` string[]
- `existing_solar_panels` string[]
- `registered_solar` boolean
- `registered_solar_storage` boolean
- `min_registered_solar_kw` number
- `has_solar_potential` boolean
- `min_panel_count` integer
- `max_panel_count` integer
- `min_capacity_kwp` number
- `max_capacity_kwp` number
- `min_yearly_energy_kwh` number
- `max_yearly_energy_kwh` number
- `min_co2_savings_kg_per_year` number
- `max_co2_savings_kg_per_year` number
- `has_3d_model` boolean
- `has_registered_business` boolean
- `registered_business_name` string
- `min_registered_business_turnover` integer
- `max_registered_business_turnover` integer
- `registered_business_turnover_currency` string
- `registered_business_financial_year` integer
- `min_registered_business_employees` integer
- `max_registered_business_employees` integer
- `has_annual_heating_estimate` boolean
- `has_thermal_assessment` boolean
- `has_peak_heat_load` boolean
- `has_recent_climate_trend` boolean
- `has_recent_temperature_extremes` boolean
- `has_recent_precipitation` boolean
- `min_recent_frost_days` number
- `max_recent_minimum_daily_temperature_c` number
- `min_recent_hot_days` number
- `min_recent_max_one_day_precipitation_mm` number
- `flood_zone` string[]
- `seismic_risk_class` string[]

## Response `200`

OK

- BuildingPage
  - `data` BuildingSummary[], 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.
  - `meta` PaginationMeta, required
    - `total` integer, required: Buildings matching, counted up to 10,000.
    - `total_is_capped` boolean, required: True when counting stopped at 10,000; narrow the box for an exact total.
    - `limit` integer, required: The page size used.
    - `offset` integer, required: The offset used.
    - `sort` 'volume' | 'area' | 'height' | 'registered_business_turnover' | 'registered_business_employees', required: The ranking used.
  - `links` Links, required
    - `next` string, uri, nullable, required: The next page's URL; null on the last page.

## 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.
- `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)