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.

Requires an API key. How to authenticate.

Query parameters50

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) 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 height is measured, not estimated.

Roof and solar

existing_solar_panelsarray of detected | none_seen | unclear: Keep buildings whose roof photo was checked for solar panels with any of these results. Buildings never checked, or whose photo was too coarse to check, match none. Repeatable or a comma list.
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, e.g. RON, CZK, EUR. Required with a turnover bound.
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.

Response 200

dataarray of BuildingSummaryrequired

building_idstring (uuid)required

The building's baseray id.

addressstring or nullrequired

Street and house number as recorded; null when the building has no address 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.

footprint_area_m2numberrequired

Ground footprint, in m².

heightHeight or any or nullrequired

Height; null when unknown.

metresnumberrequired: Height in metres.
basismeasured | estimatedrequired: measured, 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.

floorsinteger or nullrequired

Floors above ground; null when unknown.

existing_solar_panelsExistingSolarPanelsrequired

Whether solar panels are already on the roof, as a dated photo of the roof shows it.

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.

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.

registered_business_countintegerrequired≥ 0

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

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.
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.