Buildings in an area, ranked

GETapi.baseray.ai/v1/buildings

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.tech/countries lists them and takes requests for others.

Requires an API key. How to authenticate.

Query parameters57

Area and paging

bboxstringrequired: The area to search: minLon,minLat,maxLon,maxLat in WGS84 degrees. Each side may span at most 3 degrees; search a county, city or district.
sortvolume | area | height | registered_business_turnover | registered_business_employeesdefault "volume": Ranking, largest first: volume (m³), area (footprint, m²), height (m), registered_business_turnover (the largest latest turnover of a business registered at the address, in registered_business_turnover_currency, which it requires) or registered_business_employees (the largest stated size; a band ranks where it starts, so 10–19 ranks as 10).
limitinteger1–100default 25: Buildings per page, 1 to 100.
offsetinteger0–10000default 0: Buildings to skip, for the next page. offset + limit must be at most 10,000; past that, narrow bbox.

Building

categoryarray of residential_house | apartment_block | commercial | industrial | public | agricultural | ancillary | unknown: Keep buildings of any of these categories. Repeat the parameter or give a comma list: category=commercial,industrial. ancillary is an annex or outbuilding.
building_typearray of string: Keep buildings of any of these granular types, combined with category by OR: e.g. office, warehouse, school, apartments, garage. Repeatable or a comma list.
roof_shapearray of gabled | hipped | flat | pyramidal | skillion | round | mansard | half_hipped | gambrel | dome: Keep buildings with any of these roof shapes. Repeatable or a comma list.
min_floorsinteger0–500: At least this many floors above ground. Buildings where this value is unknown are left out.
max_floorsinteger0–500: At most this many floors above ground. Buildings where this value is unknown are left out.
min_dwellingsinteger0–1000000: At least this many dwellings, where known. Buildings where this value is unknown are left out.
max_dwellingsinteger0–1000000: At most this many dwellings, where known. Buildings where this value is unknown are left out.
min_entrancesinteger1–1000000: At least this many entrances (each listed address of the building counts as one). Buildings where this value is unknown are left out.
max_entrancesinteger1–1000000: At most this many entrances. Buildings where this value is unknown are left out.
address_corroborationarray of corroborated | single_source | conflicting: Keep buildings whose shown address is graded any of: corroborated (an independent record gives the same house number), single_source (only one record), conflicting (another record gives another number). Buildings shown without a house number match none.

Size

min_area_m2number0–1000000000: Minimum ground footprint, in square metres.
max_area_m2number0–1000000000: Maximum ground footprint, in square metres.
min_height_mnumber0–1000: Minimum height, in metres. Buildings where this value is unknown are left out.
max_height_mnumber0–1000: Maximum height, in metres. Buildings where this value is unknown are left out.
min_volume_m3number0–1000000000: Minimum volume, in cubic metres. Buildings where this value is unknown are left out.
max_volume_m3number0–1000000000: Maximum volume, in cubic metres. Buildings where this value is unknown are left out.
measured_height_onlybooleandefault false: Keep only buildings whose volume comes from a measurement of the building itself: a survey, or a surface model measured over its roof. Despite its name this filter reads the volume, not the height, and a volume integrated under a measured roof still has volume_basis estimated, since its heights, not its solid, were measured.

Roof and solar

solar_presencearray of registered | detected | registered_at_address | none_seen | unclear | unknown: Keep buildings whose settled solar answer, their solar_presence, is any of these. registered and detected together are the buildings known to carry panels; registered_at_address is an installation registered at an address the building shares with others; none_seen is a roof photo showing none with no register entry; unknown is neither a register entry nor a usable photo. Repeatable or a comma list.
exclude_solar_presencearray of registered | detected | registered_at_address | none_seen | unclear | unknown: Leave out buildings whose solar_presence is any of these, for example registered,detected to leave out the buildings known to carry panels. An answer may not be both kept by solar_presence and left out here. Repeatable or a comma list.
existing_solar_panelsarray of detected | none_seen | unclear: Keep buildings whose roof photo was checked for solar panels with any of these results. This reads the photo alone, whatever a register states: none_seen keeps a building with a registered installation its photo does not show. Use solar_presence for the settled answer. Buildings never checked, or whose photo was too coarse to check, match none. Repeatable or a comma list.
registered_solarboolean: true keeps buildings at whose address an official register (a grid operator's list of connected installations, or the energy regulator's licence register) states a solar installation: those whose registered_solar is not null. false keeps buildings no register states one for, which says nothing of their roofs: a register lists only what was connected to the grid, and only where its address is one a building holds. Leave it out to keep both.
registered_solar_storageboolean: Among buildings with a registered solar installation: true keeps those a register states store energy (a battery), false those stated to store none. A building whose register does not say matches neither. Not accepted with registered_solar=false.
min_registered_solar_kwnumber≤ 1000000000: At least this much installed power, in kW, registered at the building's address, counting the installations that state theirs. Where only some state it a building can match on those while its registered_solar.installed_power_kw, which is given only for a whole sum, is null. Buildings with no registered installation, or none stating its power, are left out. Not accepted with registered_solar=false.
has_solar_potentialbooleandefault false: Keep only buildings whose roof has a solar-potential estimate.
min_panel_countinteger0–1000000: At least this many solar panels fit on the roof. Buildings where this value is unknown are left out.
max_panel_countinteger0–1000000: At most this many solar panels fit on the roof. Buildings where this value is unknown are left out.
min_capacity_kwpnumber0–1000000000: Minimum rooftop solar capacity, in kWp. Buildings where this value is unknown are left out.
max_capacity_kwpnumber0–1000000000: Maximum rooftop solar capacity, in kWp. Buildings where this value is unknown are left out.
min_yearly_energy_kwhnumber0–1000000000: Minimum yearly rooftop solar energy, in kWh. Buildings where this value is unknown are left out.
max_yearly_energy_kwhnumber0–1000000000: Maximum yearly rooftop solar energy, in kWh. Buildings where this value is unknown are left out.
min_co2_savings_kg_per_yearnumber0–1000000000: Minimum CO₂ a rooftop solar installation would save, in kg a year. Buildings where this value is unknown are left out.
max_co2_savings_kg_per_yearnumber0–1000000000: Maximum CO₂ a rooftop solar installation would save, in kg a year. Buildings where this value is unknown are left out.
has_3d_modelbooleandefault false: Keep only buildings with a reconstructed 3D model of their roof.

Registered businesses

has_registered_businessbooleandefault false: Keep only buildings with at least one active business whose registered office is the building's address. A registered office is never ownership or occupancy.
registered_business_namestring2–120 characters: Keep buildings where the name of a business registered at the address contains this text.
min_registered_business_turnoverinteger: Minimum latest turnover of a business registered at the address, in whole units of registered_business_turnover_currency (required with it).
max_registered_business_turnoverinteger: Maximum latest turnover of a business registered at the address, in whole units of registered_business_turnover_currency (required with it).
registered_business_turnover_currencystring: ISO 4217 currency of the turnover bounds and of the turnover sort, e.g. RON, CZK, EUR. Required with a turnover bound or sort=registered_business_turnover.
registered_business_financial_yearinteger1990–2100: Keep buildings whose registered business's latest financial statement is for this year.
min_registered_business_employeesinteger0–1000000: At least this many employees in one business registered at the address, reading its whole stated size: a band counts only when all of it is at or above the value (10–19 matches 10, not 15). A business whose size is not stated never matches.
max_registered_business_employeesinteger0–1000000: At most this many employees in every business registered at the address whose size is stated; an open-ended top band never matches.

Energy and climate

has_annual_heating_estimatebooleandefault false: Keep only buildings with an annual heating-demand estimate for the local climate.
has_thermal_assessmentbooleandefault false: Keep only buildings with a building-specific thermal assessment (energy certificate, audit, as-built model or survey).
has_peak_heat_loadbooleandefault false: Keep only buildings whose thermal assessment supplies the design temperatures a peak heat load needs.
has_recent_climate_trendbooleandefault false: Keep only buildings with a recent rolling climate average and trend at their location.
has_recent_temperature_extremesbooleandefault false: Keep only buildings with a complete recent temperature-extremes profile at their location.
has_recent_precipitationbooleandefault false: Keep only buildings with a complete recent precipitation profile at their location.
min_recent_frost_daysnumber0–366: At least this many frost days a year, averaged over recent complete years. Buildings where this value is unknown are left out.
max_recent_minimum_daily_temperature_cnumber-100–100: The coldest daily minimum of recent complete years is at most this, in °C. Buildings where this value is unknown are left out.
min_recent_hot_daysnumber0–366: At least this many hot days a year, averaged over recent complete years. Buildings where this value is unknown are left out.
min_recent_max_one_day_precipitation_mmnumber0–5000: The wettest single day of recent complete years brought at least this much precipitation, in mm. Buildings where this value is unknown are left out.

Natural hazards

flood_zonearray of 5_year | 10_year | 20_year | 50_year | 100_year | 100_year_climate_change | 500_year | 1000_year | 10000_year: Keep buildings whose flood_zone, the most frequently flooded zone of an official flood hazard map they lie in, is any of these: zones are named by the return period of their flood, and 100_year_climate_change is the 1-in-100-year flood under the climate the map projects. Flood maps are served only where their licence allows it, and cover only the areas they were drawn for: a building whose zone is unknown matches none, so an empty result is not evidence of low flood risk. Repeatable or a comma list.
seismic_risk_classarray of RsI | RsII | RsIII | RsIV | U1 | U2 | U3 | consolidated: Keep buildings an official list of technically assessed buildings gives any of these seismic risk classes: RsI (the highest risk) to RsIV, the urgency classes U1 (the most urgent) to U3 older assessments set, or consolidated (strengthened since). Only buildings on such a list, such as Bucharest's, have a class: a building on no list matches none, which says nothing of its risk. Repeatable or a comma list.

Response 200

dataarray of BuildingSummaryrequired

building_idstring (uuid)required

The building's baseray id.

addressstring or nullrequired

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_roadstring or nullrequired

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_evidenceaddress_record | business_listing or nullrequired

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_corroborationcorroborated | single_source | conflicting or nullrequired

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_codestring or nullrequired

The official postcode of the building's address; null when none is on record.

localitystring or nullrequired

Town, city or village.

countrystring or nullrequired

ISO 3166-1 alpha-2 country code.

latitudenumberrequired

Latitude of the building's centre, WGS84.

longitudenumberrequired

Longitude of the building's centre, WGS84.

Building category; ancillary is an annex or outbuilding.

category_evidenceconfirmed | corroborated | inferred | conflicting | unconfirmedrequired

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_typestring or nullrequired

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_shapestring or nullrequired

The roof's shape, as the roof_shape filter reads it, e.g. gabled, hipped, flat; null when unknown.

footprint_area_m2numberrequired

Area of the building's outline, in m². It is the ground footprint only where the outline is drawn at the walls (outline_reference footprint on the building's detail); an outline drawn at the roof's edge (roof_edge) takes in the eaves and is larger.

heightHeight or any or nullrequired

Height; null when unknown.

metresnumberrequired: Height in metres.
basismeasured | stated | estimatedrequired: 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_m3number or nullrequired

Volume, in m³; null when unknown.

volume_basismeasured | estimated or nullrequired

Whether the volume is measured or estimated; null with the volume.

floor_areaFloorArea or any or nullrequired

Floor area, with what it rests on and what it counts; null when unknown.

square_metresnumberrequired: Floor area, in m².
basismeasured | stated | estimated or nullrequired: 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.
scopegross_whole_building | net_whole_building | gross_full_storeys | gross_above_ground or nullrequired: 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.

floorsinteger or nullrequired

Floors above ground; null when unknown.

floors_including_undergroundinteger or nullrequired

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_yearinteger or nullrequired

The year a register states the building was completed; null when none states it.

completed_by_yearinteger or nullrequired

Where a register dates the building only by a census period: the last year of that period, the year it stood by. Null otherwise.

dwellingsinteger or nullrequired

Dwellings, where known; null when unknown.

existing_solar_panelsExistingSolarPanelsrequired

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.

statusdetected | none_seen | unclear | not_checkedrequired: detected, none_seen, unclear, or not_checked (never checked, or the photo was too coarse to check).
photo_datestring (date) or nullrequired: Date of the photo checked; null when undated or never checked.
confidencenumber or nullrequired0–1: The check's confidence in its result, 0 to 1; null when not checked.
analysed_onstring (date) or nullrequired: The day the photo was checked for panels; null when never checked.
photo_resolution_cmnumber or nullrequired≥ 0: 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.

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_solarRegisteredSolar or any or nullrequired

The solar installations official registers state at the building's address; not null exactly when solar_presence is registered or registered_at_address. Null says nothing of the roof.

installation_countintegerrequired≥ 1: Installations registered at the address.
installed_power_kwnumber or nullrequired: Installed power in kW: the installations' sum where every one states its own, null otherwise, never a partial sum.
export_power_kwnumber or nullrequired: Power approved to feed the grid, in kW: the installations' sum where every one states its own, null otherwise.
storage_capacity_kwhnumber or nullrequired: 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_storageboolean or nullrequired: 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_onstring (date) or nullrequired: 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_onstring (date) or nullrequired: The latest date the installations state, of the same meaning as first_connected_on, and the same date for a single installation.
first_connected_yearinteger or nullrequired: 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_yearinteger or nullrequired: 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_countintegerrequired≥ 1: 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_addressbooleanrequired: True when address_building_count is above 1: the register then does not say which of the buildings carries the panels.
kindsarray of grid_connection | generation_licence | establishment_yearrequired: 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_throughstring (date)required: The last day of the latest month the registers report: an installation entered after it is not yet listed.

solar_potentialSolarPotential or any or nullrequired

Rooftop solar potential; null where the roof has not been modelled.

max_panel_countinteger or nullrequired: Solar panels that fit on the roof.
max_capacity_kwpnumber or nullrequired: Capacity of those panels, in kWp.
yearly_energy_kwhnumber or nullrequired: Energy they would produce in a year, in kWh.
usable_roof_area_m2number or nullrequired: Roof area usable for panels, in m².
co2_savings_kg_per_yearnumber or nullrequired: CO₂ the installation would save, in kg a year.
basismeasured | measured_cut_to_outline | estimated or nullrequired: 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_countintegerrequired≥ 0

Active businesses whose registered office is the building's address. Never ownership or occupancy.

registered_business_employeesstring or nullrequired

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_turnoverTurnover or any or nullrequired

The largest latest turnover of a business registered at the address, as the registered_business_turnover sort and filters read it; null when none is on record.

amountintegerrequired: Turnover, in whole units of currency.
currencystring or nullrequired: ISO 4217 currency of the statement.
financial_yearinteger or nullrequired: The financial year of the statement.

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_mappedbooleanrequired

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_sourcestring or nullrequired

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_gnumber or nullrequired

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.

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_yearinteger or nullrequired

The year of the assessment that set seismic_risk_class; null when not stated.

The kind of owner the building's property has on record, never who owns it: private_person (private persons or a partnership of them), social_housing (a non-profit social housing organisation), company, association (an association, foundation or self-owned institution), cooperative_housing (a housing co-operative), municipality, region, state, or other (any other owner, or owners of several of these kinds together; nothing more is on record). Null means unknown: no record states one kind for the building, as for a building divided into flats owned one by one.

app_urlstring (uri)required

The building in the baseray app.

metaPaginationMetarequired

totalintegerrequired≥ 0: Buildings matching, counted up to 10,000.
total_is_cappedbooleanrequired: True when counting stopped at 10,000; narrow the box for an exact total.
limitintegerrequired: The page size used.
offsetintegerrequired: The offset used.
sortvolume | area | height | registered_business_turnover | registered_business_employeesrequired: The ranking used.

linksLinksrequired

nextstring (uri) or nullrequired: The next page's URL; null on the last page.

Errors

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.

Every error has the same shape. Error codes.