{ "openapi": "3.1.0", "info": { "title": "baseray API", "version": "1.0.0", "description": "The baseray API gives programmatic read access to baseray's building catalogue: each building's footprint, height, volume, floor area, floors, category, address and postcode, flood zone and seismic risk, what its record states (such as its construction year) and every address, unit and record field behind it, rooftop solar potential and the roof analysis plane by plane, the local climate, energy networks and heating estimate, whether solar panels are already on the roof and what solar installation is registered at its address, and the businesses whose registered office is at its address.\n\nCoverage grows country by country. https://baseray.ai/countries lists the countries covered today and takes requests for the next ones (also through `POST /public/country-requests`). An area outside them answers with no buildings, not with an error.\n\n## Authentication\nEvery endpoint except this document and the public building pages needs a workspace API key, sent as a bearer token:\n\n Authorization: Bearer br_live_…\n\nCreate keys in the baseray app under **Settings → API keys**. A key is shown once, when it is created; store it as a secret. A key stops working when it is revoked, when it expires, or when the person who created it leaves the workspace. Cookies, sessions and other tokens are not accepted.\n\n## Rate limits and quotas\nEach key may make 60 requests a minute, and all of a workspace's keys together 5,000 requests a UTC day. Every authenticated response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the minute window resets) for the key, and `X-Daily-Quota-Limit` and `X-Daily-Quota-Remaining` for the workspace. Past a limit the API answers `429` with `rate_limited` or `quota_exceeded` and a `Retry-After` header in seconds.\n\n## Public building pages\nThe endpoints under `/public` serve the facts behind baseray's public pages and need no key. They answer the same to everyone and may be cached as their `Cache-Control` says. Each client address may make 120 requests a minute; past that they answer `429` with a `Retry-After` header. `POST /public/country-requests` is the one write: each visitor may send 20 requests an hour, and it answers in the error format below. Their field names are camelCase, every fact is its value or `null` (unknown) with `estimate` saying whether it is modelled, and their errors are `{\"error\": \"not_found\"}`, `{\"error\": \"invalid_parameter\", \"message\": \"...\"}`, `{\"error\": \"rate_limited\"}` or `{\"error\": \"unavailable\"}`.\n\n## Errors\nEvery non-2xx response outside `/public` has the same body: `{\"error\": {\"code\": \"...\", \"message\": \"...\", \"parameter\": \"...\"}}`. `code` is stable and machine-readable; `message` is for people; `parameter` names the query or path parameter at fault for `invalid_parameter`. Unknown query parameters are refused rather than ignored.\n\n## Pagination\n`GET /buildings` returns one ranked page: `meta.total` counts every match (up to 10,000; `meta.total_is_capped` is true when counting stopped there), and `links.next` is the URL of the next page, or null on the last one. `offset + limit` may not exceed 10,000; to reach further, narrow the area. `GET /buildings/{building_id}/units` pages the same way, by `limit` and `offset`, with `links.next`.\n\n## Values\nField names are snake_case (camelCase under `/public`), lengths in metres, areas in m², volumes in m³, dates `YYYY-MM-DD`, timestamps ISO 8601 UTC. A value baseray has no record of is `null`, meaning unknown, never zero. An address is given only as a record states it, and `address_evidence` says whether that is an address record of the building or a listing of a business at it: the road nearest a building no address names is `nearest_road`, never `address`. A figure's `basis` says what it rests on: `measured` (the building itself was measured), `stated` (a record states it for the building) or `estimated` (modelled, not measured). Solar potential has one more: `measured_cut_to_outline`, measured on a roof that took in the roofs attached to the building and was cut to the building's outline. A business registered at an address is never evidence that it owns or occupies the building.\n\n**Credits.** Every building an answer returns costs the workspace 1 credit, once: a building it opened (in the app, the API or an assistant) in the last 365 days is free. A page of results is charged all or nothing; when the workspace has too few credits left this month the request answers `402 insufficient_credits` and returns nothing. Credits come with a plan. A new account also gets 5 welcome credits once, for 30 days; a workspace without a plan has only what is left of those (and of credits bought earlier) until it starts a plan. `X-Credits-Charged` and `X-Credits-Remaining` say what a request cost and what is left.", "contact": { "name": "baseray", "url": "https://baseray.ai" } }, "servers": [ { "url": "https://api.baseray.ai/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Buildings", "description": "Search, look up and read buildings." }, { "name": "Registered businesses", "description": "Businesses whose registered office is a building's address. A registered office is never ownership or occupancy." }, { "name": "Public building pages", "description": "The facts behind baseray's public building and place pages. No API key; limited per client address; cacheable." }, { "name": "Countries", "description": "Ask for baseray in a country it does not cover yet. No API key; limited per visitor." }, { "name": "Removal requests", "description": "Ask for a business to be removed from baseray. No API key; limited per visitor." }, { "name": "Building reports", "description": "Buy one building's report without an account (the building pages' offer), and read it with its token. No API key; checkouts are limited per visitor, reads per report." }, { "name": "Meta", "description": "This document." } ], "paths": { "/buildings": { "get": { "tags": [ "Buildings" ], "operationId": "listBuildings", "summary": "Buildings in an area, ranked", "description": "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.", "parameters": [ { "name": "bbox", "in": "query", "required": true, "description": "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.", "schema": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$" }, "x-group": "Area and paging", "example": "25.55,45.60,25.68,45.70" }, { "name": "sort", "in": "query", "required": false, "description": "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).", "schema": { "type": "string", "enum": [ "volume", "area", "height", "registered_business_turnover", "registered_business_employees" ], "default": "volume" }, "x-group": "Area and paging" }, { "name": "limit", "in": "query", "required": false, "description": "Buildings per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "x-group": "Area and paging" }, { "name": "offset", "in": "query", "required": false, "description": "Buildings to skip, for the next page. `offset + limit` must be at most 10,000; past that, narrow `bbox`.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "x-group": "Area and paging" }, { "name": "category", "in": "query", "required": false, "description": "Keep buildings of any of these categories. Repeat the parameter or give a comma list: `category=commercial,industrial`. `ancillary` is an annex or outbuilding.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "residential_house", "apartment_block", "commercial", "industrial", "public", "agricultural", "ancillary", "unknown" ] }, "uniqueItems": true }, "x-group": "Building", "style": "form", "explode": true }, { "name": "building_type", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_]{1,64}$" }, "uniqueItems": true }, "x-group": "Building", "style": "form", "explode": true }, { "name": "roof_shape", "in": "query", "required": false, "description": "Keep buildings with any of these roof shapes. Repeatable or a comma list.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "gabled", "hipped", "flat", "pyramidal", "skillion", "round", "mansard", "half_hipped", "gambrel", "dome" ] }, "uniqueItems": true }, "x-group": "Building", "style": "form", "explode": true }, { "name": "min_floors", "in": "query", "required": false, "description": "At least this many floors above ground. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 0, "maximum": 500 }, "x-group": "Building" }, { "name": "max_floors", "in": "query", "required": false, "description": "At most this many floors above ground. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 0, "maximum": 500 }, "x-group": "Building" }, { "name": "min_dwellings", "in": "query", "required": false, "description": "At least this many dwellings, where known. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "x-group": "Building" }, { "name": "max_dwellings", "in": "query", "required": false, "description": "At most this many dwellings, where known. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "x-group": "Building" }, { "name": "min_entrances", "in": "query", "required": false, "description": "At least this many entrances (each listed address of the building counts as one). Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "x-group": "Building" }, { "name": "max_entrances", "in": "query", "required": false, "description": "At most this many entrances. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "x-group": "Building" }, { "name": "address_corroboration", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "corroborated", "single_source", "conflicting" ] }, "uniqueItems": true }, "x-group": "Building", "style": "form", "explode": true }, { "name": "min_area_m2", "in": "query", "required": false, "description": "Minimum ground footprint, in square metres.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Size" }, { "name": "max_area_m2", "in": "query", "required": false, "description": "Maximum ground footprint, in square metres.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Size" }, { "name": "min_height_m", "in": "query", "required": false, "description": "Minimum height, in metres. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000 }, "x-group": "Size" }, { "name": "max_height_m", "in": "query", "required": false, "description": "Maximum height, in metres. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000 }, "x-group": "Size" }, { "name": "min_volume_m3", "in": "query", "required": false, "description": "Minimum volume, in cubic metres. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Size" }, { "name": "max_volume_m3", "in": "query", "required": false, "description": "Maximum volume, in cubic metres. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Size" }, { "name": "measured_height_only", "in": "query", "required": false, "description": "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.", "schema": { "type": "boolean", "default": false }, "x-group": "Size" }, { "name": "solar_presence", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "registered", "detected", "registered_at_address", "none_seen", "unclear", "unknown" ] }, "uniqueItems": true }, "x-group": "Roof and solar", "style": "form", "explode": true }, { "name": "exclude_solar_presence", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "registered", "detected", "registered_at_address", "none_seen", "unclear", "unknown" ] }, "uniqueItems": true }, "x-group": "Roof and solar", "style": "form", "explode": true }, { "name": "existing_solar_panels", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "detected", "none_seen", "unclear" ] }, "uniqueItems": true }, "x-group": "Roof and solar", "style": "form", "explode": true }, { "name": "registered_solar", "in": "query", "required": false, "description": "`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.", "schema": { "type": "boolean" }, "x-group": "Roof and solar" }, { "name": "registered_solar_storage", "in": "query", "required": false, "description": "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`.", "schema": { "type": "boolean" }, "x-group": "Roof and solar" }, { "name": "min_registered_solar_kw", "in": "query", "required": false, "description": "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`.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "x-group": "Roof and solar" }, { "name": "has_solar_potential", "in": "query", "required": false, "description": "Keep only buildings whose roof has a solar-potential estimate.", "schema": { "type": "boolean", "default": false }, "x-group": "Roof and solar" }, { "name": "min_panel_count", "in": "query", "required": false, "description": "At least this many solar panels fit on the roof. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "x-group": "Roof and solar" }, { "name": "max_panel_count", "in": "query", "required": false, "description": "At most this many solar panels fit on the roof. Buildings where this value is unknown are left out.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "x-group": "Roof and solar" }, { "name": "min_capacity_kwp", "in": "query", "required": false, "description": "Minimum rooftop solar capacity, in kWp. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Roof and solar" }, { "name": "max_capacity_kwp", "in": "query", "required": false, "description": "Maximum rooftop solar capacity, in kWp. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Roof and solar" }, { "name": "min_yearly_energy_kwh", "in": "query", "required": false, "description": "Minimum yearly rooftop solar energy, in kWh. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Roof and solar" }, { "name": "max_yearly_energy_kwh", "in": "query", "required": false, "description": "Maximum yearly rooftop solar energy, in kWh. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Roof and solar" }, { "name": "min_co2_savings_kg_per_year", "in": "query", "required": false, "description": "Minimum CO₂ a rooftop solar installation would save, in kg a year. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Roof and solar" }, { "name": "max_co2_savings_kg_per_year", "in": "query", "required": false, "description": "Maximum CO₂ a rooftop solar installation would save, in kg a year. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 1000000000.0 }, "x-group": "Roof and solar" }, { "name": "has_3d_model", "in": "query", "required": false, "description": "Keep only buildings with a reconstructed 3D model of their roof.", "schema": { "type": "boolean", "default": false }, "x-group": "Roof and solar" }, { "name": "has_registered_business", "in": "query", "required": false, "description": "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.", "schema": { "type": "boolean", "default": false }, "x-group": "Registered businesses" }, { "name": "registered_business_name", "in": "query", "required": false, "description": "Keep buildings where the name of a business registered at the address contains this text.", "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "x-group": "Registered businesses" }, { "name": "min_registered_business_turnover", "in": "query", "required": false, "description": "Minimum latest turnover of a business registered at the address, in whole units of `registered_business_turnover_currency` (required with it).", "schema": { "type": "integer" }, "x-group": "Registered businesses" }, { "name": "max_registered_business_turnover", "in": "query", "required": false, "description": "Maximum latest turnover of a business registered at the address, in whole units of `registered_business_turnover_currency` (required with it).", "schema": { "type": "integer" }, "x-group": "Registered businesses" }, { "name": "registered_business_turnover_currency", "in": "query", "required": false, "description": "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`.", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "x-group": "Registered businesses", "example": "RON" }, { "name": "registered_business_financial_year", "in": "query", "required": false, "description": "Keep buildings whose registered business's latest financial statement is for this year.", "schema": { "type": "integer", "minimum": 1990, "maximum": 2100 }, "x-group": "Registered businesses" }, { "name": "min_registered_business_employees", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "x-group": "Registered businesses" }, { "name": "max_registered_business_employees", "in": "query", "required": false, "description": "At most this many employees in every business registered at the address whose size is stated; an open-ended top band never matches.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "x-group": "Registered businesses" }, { "name": "has_annual_heating_estimate", "in": "query", "required": false, "description": "Keep only buildings with an annual heating-demand estimate for the local climate.", "schema": { "type": "boolean", "default": false }, "x-group": "Energy and climate" }, { "name": "has_thermal_assessment", "in": "query", "required": false, "description": "Keep only buildings with a building-specific thermal assessment (energy certificate, audit, as-built model or survey).", "schema": { "type": "boolean", "default": false }, "x-group": "Energy and climate" }, { "name": "has_peak_heat_load", "in": "query", "required": false, "description": "Keep only buildings whose thermal assessment supplies the design temperatures a peak heat load needs.", "schema": { "type": "boolean", "default": false }, "x-group": "Energy and climate" }, { "name": "has_recent_climate_trend", "in": "query", "required": false, "description": "Keep only buildings with a recent rolling climate average and trend at their location.", "schema": { "type": "boolean", "default": false }, "x-group": "Energy and climate" }, { "name": "has_recent_temperature_extremes", "in": "query", "required": false, "description": "Keep only buildings with a complete recent temperature-extremes profile at their location.", "schema": { "type": "boolean", "default": false }, "x-group": "Energy and climate" }, { "name": "has_recent_precipitation", "in": "query", "required": false, "description": "Keep only buildings with a complete recent precipitation profile at their location.", "schema": { "type": "boolean", "default": false }, "x-group": "Energy and climate" }, { "name": "min_recent_frost_days", "in": "query", "required": false, "description": "At least this many frost days a year, averaged over recent complete years. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 366 }, "x-group": "Energy and climate" }, { "name": "max_recent_minimum_daily_temperature_c", "in": "query", "required": false, "description": "The coldest daily minimum of recent complete years is at most this, in °C. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": -100, "maximum": 100 }, "x-group": "Energy and climate" }, { "name": "min_recent_hot_days", "in": "query", "required": false, "description": "At least this many hot days a year, averaged over recent complete years. Buildings where this value is unknown are left out.", "schema": { "type": "number", "minimum": 0, "maximum": 366 }, "x-group": "Energy and climate" }, { "name": "min_recent_max_one_day_precipitation_mm", "in": "query", "required": false, "description": "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.", "schema": { "type": "number", "minimum": 0, "maximum": 5000 }, "x-group": "Energy and climate" }, { "name": "flood_zone", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "5_year", "10_year", "20_year", "50_year", "100_year", "100_year_climate_change", "500_year", "1000_year", "10000_year" ] }, "uniqueItems": true }, "x-group": "Natural hazards", "style": "form", "explode": true }, { "name": "seismic_risk_class", "in": "query", "required": false, "description": "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.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "RsI", "RsII", "RsIII", "RsIV", "U1", "U2", "U3", "consolidated" ] }, "uniqueItems": true }, "x-group": "Natural hazards", "style": "form", "explode": true } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Daily-Quota-Limit": { "$ref": "#/components/headers/X-Daily-Quota-Limit" }, "X-Daily-Quota-Remaining": { "$ref": "#/components/headers/X-Daily-Quota-Remaining" }, "X-Credits-Charged": { "$ref": "#/components/headers/X-Credits-Charged" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingPage" }, "examples": { "example": { "summary": "Bulevardul 15 Noiembrie 78, Brașov, as read from the live app on 25 Sep 2026. The fields added since that reading (`postal_code`, `address_evidence`, `address_corroboration`, `building_type`, `roof_shape`, `floor_area`, the registered-business fields, `solar_potential` and the natural-hazard fields) are shown for illustration only.", "value": { "data": [ { "building_id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "address": "Bulevardul 15 Noiembrie 78", "nearest_road": null, "address_evidence": "address_record", "address_corroboration": "single_source", "postal_code": null, "locality": "Brașov", "country": "RO", "latitude": 45.64988, "longitude": 25.61044, "category": "commercial", "category_evidence": "confirmed", "building_type": "retail", "roof_shape": "flat", "footprint_area_m2": 31252.0, "height": { "metres": 18.0, "basis": "estimated" }, "volume_m3": 562531.0, "volume_basis": "estimated", "floor_area": { "square_metres": 500032.0, "basis": "estimated", "scope": "gross_above_ground" }, "floors": 16, "floors_including_underground": null, "construction_year": null, "completed_by_year": null, "dwellings": null, "existing_solar_panels": { "status": "none_seen", "photo_date": "2022-09-08", "confidence": 0.988, "analysed_on": null, "photo_resolution_cm": null }, "solar_presence": "none_seen", "registered_solar": null, "solar_potential": null, "registered_business_count": 0, "registered_business_employees": null, "registered_business_turnover": null, "flood_zone": null, "flood_zone_mapped": false, "flood_zone_source": null, "seismic_design_acceleration_g": null, "seismic_risk_class": null, "seismic_risk_assessment_year": null, "app_url": "https://app.baseray.ai/?building=c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ], "meta": { "total": 1, "total_is_capped": false, "limit": 25, "offset": 0, "sort": "volume" }, "links": { "next": null } } } } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } } } }, "/buildings/at": { "get": { "tags": [ "Buildings" ], "operationId": "findBuildingsAtPoint", "summary": "Buildings at a point", "description": "The buildings whose outline lies within `radius_m` of a point, nearest first. An area outside the countries baseray covers answers with no buildings; https://baseray.ai/countries lists them and takes requests for others.", "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude of the point, WGS84.", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 45.64988 }, { "name": "lon", "in": "query", "required": true, "description": "Longitude of the point, WGS84.", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": 25.61044 }, { "name": "radius_m", "in": "query", "required": false, "description": "How far from the point to look, in metres.", "schema": { "type": "number", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "limit", "in": "query", "required": false, "description": "How many buildings to return, nearest first.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Daily-Quota-Limit": { "$ref": "#/components/headers/X-Daily-Quota-Limit" }, "X-Daily-Quota-Remaining": { "$ref": "#/components/headers/X-Daily-Quota-Remaining" }, "X-Credits-Charged": { "$ref": "#/components/headers/X-Credits-Charged" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingList" }, "examples": { "example": { "summary": "Bulevardul 15 Noiembrie 78, Brașov, as read from the live app on 25 Sep 2026. The fields added since that reading (`postal_code`, `address_evidence`, `address_corroboration`, `building_type`, `roof_shape`, `floor_area`, the registered-business fields, `solar_potential` and the natural-hazard fields) are shown for illustration only.", "value": { "data": [ { "building_id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "address": "Bulevardul 15 Noiembrie 78", "nearest_road": null, "address_evidence": "address_record", "address_corroboration": "single_source", "postal_code": null, "locality": "Brașov", "country": "RO", "latitude": 45.64988, "longitude": 25.61044, "category": "commercial", "category_evidence": "confirmed", "building_type": "retail", "roof_shape": "flat", "footprint_area_m2": 31252.0, "height": { "metres": 18.0, "basis": "estimated" }, "volume_m3": 562531.0, "volume_basis": "estimated", "floor_area": { "square_metres": 500032.0, "basis": "estimated", "scope": "gross_above_ground" }, "floors": 16, "floors_including_underground": null, "construction_year": null, "completed_by_year": null, "dwellings": null, "existing_solar_panels": { "status": "none_seen", "photo_date": "2022-09-08", "confidence": 0.988, "analysed_on": null, "photo_resolution_cm": null }, "solar_presence": "none_seen", "registered_solar": null, "solar_potential": null, "registered_business_count": 0, "registered_business_employees": null, "registered_business_turnover": null, "flood_zone": null, "flood_zone_mapped": false, "flood_zone_source": null, "seismic_design_acceleration_g": null, "seismic_risk_class": null, "seismic_risk_assessment_year": null, "app_url": "https://app.baseray.ai/?building=c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ] } } } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } } } }, "/buildings/{building_id}": { "get": { "tags": [ "Buildings" ], "operationId": "getBuilding", "summary": "One building", "description": "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`.", "parameters": [ { "name": "building_id", "in": "path", "required": true, "description": "The building's baseray id, a UUID returned by the other building endpoints.", "schema": { "type": "string", "format": "uuid" }, "example": "c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Daily-Quota-Limit": { "$ref": "#/components/headers/X-Daily-Quota-Limit" }, "X-Daily-Quota-Remaining": { "$ref": "#/components/headers/X-Daily-Quota-Remaining" }, "X-Credits-Charged": { "$ref": "#/components/headers/X-Credits-Charged" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingDetailEnvelope" }, "examples": { "example": { "summary": "Bulevardul 15 Noiembrie 78, Brașov, as read from the live app on 25 Sep 2026. The fields added since that reading (`postal_code`, `address_evidence`, `address_corroboration`, `building_type`, `roof_shape`, `floor_area`, the registered-business fields, `solar_potential` and the natural-hazard fields) are shown for illustration only. `dwellings`, `entrances` and `outline_reference` are shown as null, and `stated_facts` and `parts` empty, for illustration. `addresses`, `units`, `record_sheet`, `climate`, `energy_networks` and `heating_estimate` are shown for illustration only.", "value": { "data": { "building_id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "address": "Bulevardul 15 Noiembrie 78", "nearest_road": null, "address_evidence": "address_record", "address_corroboration": "single_source", "postal_code": null, "locality": "Brașov", "country": "RO", "latitude": 45.64988, "longitude": 25.61044, "category": "commercial", "category_evidence": "confirmed", "building_type": "retail", "roof_shape": "flat", "footprint_area_m2": 31252.0, "height": { "metres": 18.0, "basis": "estimated" }, "volume_m3": 562531.0, "volume_basis": "estimated", "floor_area": { "square_metres": 500032.0, "basis": "estimated", "scope": "gross_above_ground" }, "floors": 16, "floors_including_underground": null, "construction_year": null, "completed_by_year": null, "dwellings": null, "existing_solar_panels": { "status": "none_seen", "photo_date": "2022-09-08", "confidence": 0.988, "analysed_on": null, "photo_resolution_cm": null }, "solar_presence": "none_seen", "registered_solar": null, "solar_potential": null, "registered_business_count": 0, "registered_business_employees": null, "registered_business_turnover": null, "flood_zone": null, "flood_zone_mapped": false, "flood_zone_source": null, "seismic_design_acceleration_g": null, "seismic_risk_class": null, "seismic_risk_assessment_year": null, "app_url": "https://app.baseray.ai/?building=c9eefd1b-8c8d-48fe-8b72-e015374d7720", "entrances": null, "stated_facts": [], "is_current": true, "replaced_by_building_id": null, "outline_reference": null, "parts": [], "eave_height_m": null, "has_3d_model": null, "addresses": { "confirmation": "confirmed", "addresses": [ { "line": "Strada Memorandumului 28, bl. A, sc. 1", "postal_code": "400114", "locality": "Cluj-Napoca", "entrance": "1", "dwellings_at_entrance": 24, "relation": "shown" } ] }, "units": { "listed": 118, "listed_dwellings": 96, "stated": 118, "stated_dwellings": 96, "list_is_complete": true, "by_floor": [ { "floor_kind": "ground", "floor_number": null, "units": 22, "dwellings": 0 }, { "floor_kind": "upper", "floor_number": 1, "units": 24, "dwellings": 24 } ], "by_kind": [ { "kind": "dwelling", "units": 96 }, { "kind": "commercial", "units": 4 }, { "kind": "storage", "units": 18 } ], "entrances": [ "A", "B" ], "entrance_dwellings": [] }, "record_sheet": { "exists": true, "validated": true, "cadastral_number": "262812-C1", "property_number": null, "land_book_number": "262812", "read_on": "2026-10-06", "sections": [ { "title": "Performance", "rows": [ { "label": "Heated floor area", "value": 2410.5, "unit": "m2" } ] } ] }, "roof_analysis": null, "climate": { "periods": [ { "period": "recent_average", "from": "2016", "to": "2025", "data_through": "2025-12-31", "coldest_day_c": -14.2, "hottest_day_c": 36.8, "frost_days": 92.4, "hot_days": 31.5, "precipitation_mm": 612.3, "wet_days": 104.2, "wettest_day_mm": 48.6 } ], "heating_degree_days": [ { "period": "standard_normal", "from": "1991", "to": "2020", "degree_days": 3202.0 } ], "temperature_trend_c_per_decade": 0.48 }, "energy_networks": [ { "network": "natural_gas", "level": "street", "present": true, "year": 2024 } ], "heating_estimate": { "useful_heat_kwh_per_year": 182000.0, "useful_heat_low_kwh_per_year": null, "useful_heat_high_kwh_per_year": null, "useful_heat_kwh_per_m2_per_year": 75.5, "heated_floor_area_m2": 2410.5, "heated_floor_area_basis": "register_heated_area", "useful_heat_kwh_per_dwelling_per_year": 7583.0, "dwelling_count": 24, "delivered_energy_kwh_per_year": 214000.0, "expected_energy_kwh_per_year": 196000.0, "peak_heat_load_kw": 96.4, "peak_heat_load_basis": "screening_estimate", "design_outdoor_temperature_c": -15.0, "hot_water_heat_kwh_per_year": 41000.0, "hot_water_persons": 52.8, "hot_water_occupancy_basis": "counted_dwellings", "construction_period_is_on_record": true, "era_scenarios": [], "neighbours_are_measured": true, "neighbour_wall_share": 0.18, "heat_pump_scenarios": [ { "seasonal_performance_factor": 3.0, "electricity_kwh_per_year": 60667.0 } ] } } } } } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/buildings/{building_id}/registered-businesses": { "get": { "tags": [ "Registered businesses" ], "operationId": "listBuildingRegisteredBusinesses", "summary": "Businesses registered at a building's address", "description": "The active businesses whose registered office is the building's exact official address, largest first, at most 25; `meta.total` counts them all. A registered office is never ownership or occupancy. A business its register protects from direct marketing is marked `advertising_protected`: its data may not be used for direct marketing.", "parameters": [ { "name": "building_id", "in": "path", "required": true, "description": "The building's baseray id, a UUID returned by the other building endpoints.", "schema": { "type": "string", "format": "uuid" }, "example": "c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Daily-Quota-Limit": { "$ref": "#/components/headers/X-Daily-Quota-Limit" }, "X-Daily-Quota-Remaining": { "$ref": "#/components/headers/X-Daily-Quota-Remaining" }, "X-Credits-Charged": { "$ref": "#/components/headers/X-Credits-Charged" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisteredBusinessList" }, "examples": { "example": { "summary": "Illustrative placeholder, not a real business.", "value": { "data": [ { "name": "Example Business SRL", "registration_number": "00000000", "country": "RO", "employees": "10–49", "employees_stated_for": "FY 2024", "advertising_protected": null, "natural_person": null, "legal_form": null, "person_kind": null, "ceased_on": null } ], "meta": { "total": 1, "sources": [] } } } } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/buildings/{building_id}/units": { "get": { "tags": [ "Buildings" ], "operationId": "listBuildingUnits", "summary": "A building's units", "description": "The units a building's record lists (flats, shops, parking spaces, storage), each with its number, name or door, its floor as the record words it and as a kind and number, and its entrance, kind, use, area, rooms and cadastral number where the record states them. `unit` finds units by their number or name (\"275\" finds 275, \"Ap. 275\" and \"Parcare 275\", never 1275); without it the list comes a page at a time. `meta.list_is_complete` is false when the record states a total that differs from its list: a unit missing from the list may then still exist. A building with no units listed has unknown units, never none. Costs what opening the building costs: free once opened.", "parameters": [ { "name": "building_id", "in": "path", "required": true, "description": "The building's baseray id, a UUID returned by the other building endpoints.", "schema": { "type": "string", "format": "uuid" }, "example": "c9eefd1b-8c8d-48fe-8b72-e015374d7720" }, { "name": "unit", "in": "query", "required": false, "description": "The number or name of the unit(s) to find, e.g. `275`, `12A` or `Parcare 3`; 1 to 100 characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "example": "275" }, { "name": "limit", "in": "query", "required": false, "description": "Units per page, 1 to 500. Default 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } }, { "name": "offset", "in": "query", "required": false, "description": "Matched units to skip, 0 to 100,000. Default 0.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Daily-Quota-Limit": { "$ref": "#/components/headers/X-Daily-Quota-Limit" }, "X-Daily-Quota-Remaining": { "$ref": "#/components/headers/X-Daily-Quota-Remaining" }, "X-Credits-Charged": { "$ref": "#/components/headers/X-Credits-Charged" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingUnitPage" }, "examples": { "example": { "summary": "Flat 275 of a 736-unit block, for illustration.", "value": { "data": [ { "designation": "275", "floor": "ETAJ 7", "floor_kind": "upper", "floor_number": 7, "entrance": "B", "kind": "dwelling", "use": "locuinta", "area_m2": 54.2, "rooms": 2, "cadastral_number": null } ], "meta": { "listed": 736, "stated": 736, "list_is_complete": true, "matched": 1, "limit": 200, "offset": 0 }, "links": { "next": null } } } } } } }, "400": { "$ref": "#/components/responses/InvalidParameter" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/openapi.json": { "get": { "tags": [ "Meta" ], "operationId": "getOpenApiDocument", "summary": "This document", "security": [], "description": "The OpenAPI 3.1 document of this API. Public and cacheable (`Cache-Control: public, max-age=3600`, `ETag`).", "responses": { "200": { "description": "The OpenAPI document.", "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified since the `ETag` given in `If-None-Match`." } } } }, "/public/buildings/{building_id}": { "get": { "tags": [ "Public building pages" ], "operationId": "getPublicBuilding", "summary": "One building's public page", "security": [], "description": "The public facts of one building that has a public page: in Czechia an addressed building whose register gives its floors, completion date and use; in Romania an addressed building whose register gives at least two of floors, construction year and floor area. Any other building answers 404. A retired building whose replacement has a public page answers 301: its page moved for good to that one.", "parameters": [ { "name": "building_id", "in": "path", "required": true, "description": "The building's baseray id.", "schema": { "type": "string", "format": "uuid" }, "example": "c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBuilding" }, "examples": { "example": { "value": { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "country": "cz", "slug": "praha-vinohradska-12", "address": { "street": "Vinohradská", "number": "12", "locality": "Praha", "district": "Praha 2", "county": "Hlavní město Praha", "postcode": "12000", "label": "Vinohradská 1200/12, 120 00 Praha 2" }, "facts": { "use": { "value": "residential_multi", "label": "Bytový dům", "estimate": false }, "floors": { "value": 6, "estimate": false, "includesUnderground": false }, "built": { "year": null, "era": "1919–1945", "estimate": false }, "footprintArea": { "value": 412.5, "unit": "m2", "estimate": false }, "floorArea": { "value": null, "unit": "m2", "scope": null, "estimate": false }, "height": { "value": 21.4, "unit": "m", "estimate": false }, "volume": { "value": 8800, "unit": "m3", "estimate": true }, "roofArea": { "value": 430, "unit": "m2", "estimate": true }, "roofShape": { "value": "flat", "estimate": true }, "dwellings": { "value": 24, "estimate": false }, "floodZone": null, "seismicZone": null, "cadastralRef": { "value": "1200", "officialUrl": "https://nahlizenidokn.cuzk.cz/" } }, "outline": { "type": "Polygon", "coordinates": [ [ [ 14.4301, 50.0751 ], [ 14.4305, 50.0751 ], [ 14.4305, 50.0754 ], [ 14.4301, 50.0754 ], [ 14.4301, 50.0751 ] ] ] }, "centroid": [ 14.4303, 50.07525 ], "context": { "streetBuildings": 38, "olderThanShareOnStreet": 0.71, "tallerThanShareInLocality": 0.84 }, "place": { "country": "cz", "slug": "praha", "name": "Praha" }, "gated": { "solarChecked": true, "registeredCompanies": 3 }, "updatedAt": "2026-10-01" } } } } } }, "301": { "description": "The building was retired and replaced: its page moved for good to the page of the building that replaced it, which `Location` and the body name. Kept an hour, like a refusal, so a replacement that gains or loses its page is followed within the hour.", "headers": { "Location": { "description": "The replacement's public page, `/v1/public/buildings/{building_id}`.", "schema": { "type": "string" } }, "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBuildingMoved" }, "examples": { "example": { "value": { "movedTo": { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "country": "cz", "slug": "praha-vinohradska-12" } } } } } } }, "404": { "$ref": "#/components/responses/PublicNotFound" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/buildings/{building_id}/preview.png": { "get": { "tags": [ "Public building pages" ], "operationId": "getPublicBuildingPreview", "summary": "One building's preview image", "security": [], "description": "A 1200×630 PNG preview of one building that has a public page, for link previews and social cards. Any other building answers 404, as its page does.", "parameters": [ { "name": "building_id", "in": "path", "required": true, "description": "The building's baseray id.", "schema": { "type": "string", "format": "uuid" }, "example": "c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ], "responses": { "200": { "description": "The preview image.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "image/png": { "schema": { "type": "string", "contentMediaType": "image/png" } } } }, "404": { "$ref": "#/components/responses/PublicNotFound" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/buildings/{building_id}/model3d": { "get": { "tags": [ "Public building pages" ], "operationId": "getPublicBuildingModel3D", "summary": "One building's 3D model", "security": [], "description": "What one building that has a public page is drawn in 3D from. A shell is served (`lod2`) only where it was measured from open data, with the credit its licence asks for; a shell measured from paid imagery never is. Otherwise the outline is raised to the height the page shows (`extruded`), or drawn flat where the page shows none (`flat`): no height is ever guessed. Any other building answers 404, as its page does.", "parameters": [ { "name": "building_id", "in": "path", "required": true, "description": "The building's baseray id.", "schema": { "type": "string", "format": "uuid" }, "example": "c9eefd1b-8c8d-48fe-8b72-e015374d7720" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBuildingModel3D" }, "examples": { "example": { "value": { "buildingId": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "kind": "lod2", "heightM": 9.6, "heightOnRecord": true, "source": { "label": "Klimadatastyrelsen DHM lidar", "licence": "CC BY 4.0", "url": "https://datafordeler.dk/dataoversigt/danmarks-hoejdemodel-dhm/" }, "outline": [ [ -6.12, -4.05 ], [ 6.12, -4.05 ], [ 6.12, 4.05 ], [ -6.12, 4.05 ] ], "holes": [], "mesh": { "vertices": [ [ -6.12, -4.05, 6.2 ], [ 6.12, -4.05, 6.2 ], [ 6.12, 4.05, 6.2 ], [ -6.12, 4.05, 6.2 ], [ 0.0, 0.0, 9.6 ] ], "faces": [ [ 0, 1, 4 ], [ 1, 2, 4 ], [ 2, 3, 4 ], [ 3, 0, 4 ] ] } } } } } } }, "404": { "$ref": "#/components/responses/PublicNotFound" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/buildings": { "get": { "tags": [ "Public building pages" ], "operationId": "listPublicBuildings", "summary": "Buildings with a public page", "security": [], "description": "A country's buildings that have a public page, in a stable order, for sitemaps. Follow `nextCursor` until it is null.", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "cz" }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page; omit for the first page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Buildings per page, at most 50,000.", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 50000 } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBuildingIndex" }, "examples": { "example": { "value": { "items": [ { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "slug": "praha-vinohradska-12", "updatedAt": "2026-10-01" } ], "nextCursor": "eyJrIjoiYzllZSJ9", "total": 2210000 } } } } } }, "400": { "$ref": "#/components/responses/PublicInvalidParameter" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/address-search": { "get": { "tags": [ "Public building pages" ], "operationId": "searchPublicAddresses", "summary": "Address check", "security": [], "description": "Up to ten addressed buildings matching a text, for the free address check. A building without a public page is returned with `indexable` false.", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "cz" }, { "name": "q", "in": "query", "required": true, "description": "The address text, e.g. `Vinohradská 12`.", "schema": { "type": "string" }, "example": "Vinohradská 12" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAddressSearchResult" }, "examples": { "example": { "value": { "items": [ { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "slug": "praha-vinohradska-12", "label": "Vinohradská 1200/12, 120 00 Praha 2", "indexable": true } ] } } } } } }, "400": { "$ref": "#/components/responses/PublicInvalidParameter" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/places": { "get": { "tags": [ "Public building pages" ], "operationId": "listPublicPlaces", "summary": "Places with a statistics page", "security": [], "description": "A country's towns with a statistics page.", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "cz" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPlaceList" }, "examples": { "example": { "value": { "items": [ { "slug": "iasi", "name": "Iași", "county": "Iași", "buildings": 61234, "indexableBuildings": 18000, "streets": 412 } ] } } } } } }, "400": { "$ref": "#/components/responses/PublicInvalidParameter" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/places/{country}/{slug}/stats": { "get": { "tags": [ "Public building pages" ], "operationId": "getPublicPlaceStatistics", "summary": "A place's building statistics", "security": [], "description": "How many buildings a place has, how old and how tall they are, its tallest buildings and rooftop solar counts.", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "ro" }, { "name": "slug", "in": "path", "required": true, "description": "The place's slug, from `/public/places`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" }, "example": "iasi" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPlaceStatistics" }, "examples": { "example": { "value": { "name": "Iași", "county": "Iași", "buildings": 61234, "addressed": 40211, "built": { "known": 18000, "byEra": [ { "era": "before 1945", "count": 1200 } ], "before1978Share": 0.46 }, "floors": { "known": 30000, "histogram": [ { "floors": "1", "count": 21000 } ], "blocks4plus": 3100 }, "tallest": [ { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "slug": "iasi-palas", "height": 72.0, "label": "Strada Palat 1, Iași" } ], "solar": { "checkedRoofs": 9000, "withPanels": 1450, "imageryYears": [ 2023, 2024 ] }, "roofAreaTotalM2": 5400000, "registeredCompanies": 15400, "updatedAt": "2026-10-01" } } } } } }, "404": { "$ref": "#/components/responses/PublicNotFound" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/places/{country}/{slug}/streets": { "get": { "tags": [ "Public building pages" ], "operationId": "listPublicStreets", "summary": "A place's streets with their own page", "security": [], "description": "The place's streets where at least 3 buildings have a public page, by name.", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "cz" }, { "name": "slug", "in": "path", "required": true, "description": "The place's slug, from `/public/places`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" }, "example": "praha" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStreetList" }, "examples": { "example": { "value": { "items": [ { "slug": "milevska", "name": "Milevská", "locality": "Praha", "buildings": 24, "updatedAt": "2026-09-30" } ] } } } } } }, "404": { "$ref": "#/components/responses/PublicNotFound" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/places/{country}/{slug}/streets/{street}": { "get": { "tags": [ "Public building pages" ], "operationId": "getPublicStreet", "summary": "A street's page", "security": [], "description": "One street of a place and every building on it with a public page, by house number.", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "cz" }, { "name": "slug", "in": "path", "required": true, "description": "The place's slug, from `/public/places`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" }, "example": "praha" }, { "name": "street", "in": "path", "required": true, "description": "The street's slug, from `/public/places/{country}/{slug}/streets`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" }, "example": "milevska" } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStreet" }, "examples": { "example": { "value": { "slug": "milevska", "name": "Milevská", "locality": "Praha", "buildings": 24, "updatedAt": "2026-09-30", "place": { "country": "cz", "slug": "praha", "name": "Praha" }, "county": "Hlavní město Praha", "items": [ { "id": "a152dedd-bf51-4bdc-897e-98e1e5e35280", "country": "cz", "slug": "praha-milevska-2094-3", "label": "Milevská 2094/3, Krč, 140 00 Praha 4", "number": "2094/3", "use": "bytový dům", "floors": { "value": 33, "includesUnderground": true }, "built": { "year": 2017, "era": null } } ] } } } } } }, "404": { "$ref": "#/components/responses/PublicNotFound" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/streets": { "get": { "tags": [ "Public building pages" ], "operationId": "listPublicStreetPages", "summary": "Streets with their own page", "security": [], "description": "A country's street pages, larger places and longer streets first, for sitemaps. `cursor` is a position: page n of `limit` starts at `cursor=(n−1)·limit`.", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "`cz` (Czechia) or `ro` (Romania).", "schema": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "example": "cz" }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page (a position); omit for the first page.", "schema": { "type": "string", "pattern": "^[0-9]{1,9}$" } }, { "name": "limit", "in": "query", "required": false, "description": "Streets per page, at most 50,000.", "schema": { "type": "integer", "minimum": 1, "maximum": 50000 }, "example": 10000 } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "$ref": "#/components/headers/Public-Cache-Control" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStreetIndex" }, "examples": { "example": { "value": { "items": [ { "place": "praha", "slug": "milevska", "updatedAt": "2026-09-30" } ], "nextCursor": "10000", "total": 74433 } } } } } }, "400": { "$ref": "#/components/responses/PublicInvalidParameter" }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "503": { "$ref": "#/components/responses/PublicUnavailable" } } } }, "/public/country-requests": { "post": { "tags": [ "Countries" ], "operationId": "requestCountry", "summary": "Request a country", "security": [], "description": "Asks for baseray in a country it does not cover yet, for a person who agrees to be emailed when it does. One request per address and country: asking again changes nothing and answers the same, so the answer never tells whether an address had asked before. A country baseray already covers answers `live` and stores nothing. The address is never shown or shared; product analytics count the country only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryRequest" }, "examples": { "example": { "value": { "country": "DE", "email": "ana@example.com", "consent": true, "company": "Example GmbH", "use_case": "insurance_underwriting", "locale": "en" } } } } } }, "responses": { "202": { "description": "Received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryRequestReceipt" }, "examples": { "example": { "value": { "status": "received", "country": "DE" } } } } } }, "200": { "description": "baseray already covers this country; nothing was stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryRequestReceipt" }, "examples": { "example": { "value": { "status": "live", "country": "RO" } } } } } }, "400": { "description": "A field is missing, malformed or unknown (`invalid_parameter`); `parameter` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "value": { "error": { "code": "invalid_parameter", "message": "consent must be true: the person agrees to be emailed when baseray covers the country.", "parameter": "consent" } } } } } } }, "429": { "description": "Too many country requests from this visitor in an hour (`rate_limited`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "value": { "error": { "code": "rate_limited", "message": "Too many country requests from this address; retry after 1800 seconds." } } } } } } } } } }, "/public/removal-requests": { "post": { "tags": [ "Removal requests" ], "operationId": "requestRemoval", "summary": "Ask for a business to be removed", "security": [], "description": "Asks for a business to be removed from baseray (GDPR Art. 21), by its country and register number. A business its register makes a person's (a sole trader or personally owned business, or an estate) is removed without a reason asked: from the app, the API, AI assistants, exports, public pages and counts, and it is not imported again while its register lists it. Any other business is decided within 7 days (72 hours when `personal_safety` is true). Customers who exported the business in the past 24 months are asked to delete it. The answer is the same whether or not baseray holds the business.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalRequest" }, "examples": { "example": { "value": { "country": "DK", "registration_number": "12345678", "production_unit_numbers": [ "1012345678" ], "email": "owner@example.dk", "personal_safety": false, "locale": "da" } } } } } }, "responses": { "202": { "description": "Received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalRequestReceipt" }, "examples": { "example": { "value": { "status": "received", "reference": "5b0f3c5e-8f2d-4c1a-9a77-2f6b1d9e4c21" } } } } } }, "400": { "description": "A field is missing, malformed or unknown (`invalid_parameter`); `parameter` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "value": { "error": { "code": "invalid_parameter", "message": "registration_number must be a CVR number of 8 digits.", "parameter": "registration_number" } } } } } } }, "429": { "description": "Too many removal requests from this visitor in an hour (`rate_limited`); retry after `Retry-After` seconds, or write to privacy@baseray.ai.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "example": { "value": { "error": { "code": "rate_limited", "message": "Too many removal requests from this address; retry after 1800 seconds, or write to privacy@baseray.ai." } } } } } } } } } }, "/public/building-reports/checkout": { "post": { "tags": [ "Building reports" ], "operationId": "startBuildingReportCheckout", "summary": "Buy a building's report", "security": [], "description": "Starts a Stripe Checkout for one building's report, at its final price (tax included), without an account. Sold only for a building whose public page is indexable (enough register facts) and only while Stripe takes live charges. The buyer must ask for immediate delivery and accept losing the right of withdrawal on delivery, and accept the terms (`consent`). After paying, Checkout returns to the report's page in the app; when abandoned, to `returnPath` on baseray.ai. Limited per visitor (the website names the visitor).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportCheckoutRequest" }, "examples": { "example": { "value": { "buildingId": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "locale": "cs", "returnPath": "/cs/budova/praha-vinohradska-12-c9eefd1b-8c8d-48fe-8b72-e015374d7720", "consent": { "withdrawalWaiver": true, "terms": true }, "attribution": { "utmSource": "google", "landingPath": "/cs/budova/praha-vinohradska-12-c9eefd1b-8c8d-48fe-8b72-e015374d7720", "callToAction": "report_offer" }, "analyticsAnonymousId": "0192f0a1-7c3e-7d2b-9a51-3f0c2e7b8d14", "analyticsSessionId": "0192f0a1-7c3e-7d2b-9a51-3f0c2e7b8d15" } } } } } }, "responses": { "201": { "description": "The Checkout to send the buyer to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportCheckout" }, "examples": { "example": { "value": { "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3" } } } } } }, "404": { "description": "No building with a public page has this id (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "not_found", "message": "No building with a public page has this id." } } } } } }, "409": { "description": "The building's public page is not indexable: too few register facts for a report (`report_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "report_unavailable", "message": "The register holds too few facts about this building for a report." } } } } } }, "422": { "description": "Both boxes not ticked (`consent_required`), or a field missing, malformed or unknown (`invalid_parameter`); `parameter` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "consent": { "value": { "code": "consent_required", "message": "consent.withdrawalWaiver and consent.terms must both be true: the buyer asks for the report at once, accepts losing the right of withdrawal on delivery, and accepts the terms.", "parameter": "consent" } }, "returnPath": { "value": { "code": "invalid_parameter", "message": "returnPath must be this building's page in the locale's language, such as /cs/budova/{slug}-c9eefd1b-8c8d-48fe-8b72-e015374d7720.", "parameter": "returnPath" } } } } } }, "429": { "description": "Too many report checkouts from this visitor in an hour (`rate_limited`); retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "rate_limited", "message": "Too many requests; retry after 1800 seconds." } } } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "503": { "description": "Stripe takes no live charges now (`payments_unavailable`), or the building catalogue or Stripe cannot be reached (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "payments": { "value": { "code": "payments_unavailable", "message": "Reports cannot be paid for right now. Write to hello@baseray.ai." } } } } } } } } }, "/public/building-reports/{token}": { "get": { "tags": [ "Building reports" ], "operationId": "getBuildingReport", "summary": "A bought report", "security": [], "description": "The report a token opens. While its Checkout is open the report is first settled from Stripe's current state, so it reads `paid` as soon as Stripe has the payment. A paid report opens its building for 12 months from payment (`accessUntil`). Limited per report: 240 reads a minute with one token, its building's reads included.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The report's token: 43 base64url characters, from the report's link (`https://app.baseray.ai/report/{token}`).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "example": "qJ3x9Yb0t2Wc5nVh8kLmZpR4sT6uE1aD7fG0hJ2kL9w" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReport" }, "examples": { "example": { "value": { "status": "paid", "building": { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "country": "cz", "title": "Vinohradská 1200/12, 120 00 Praha 2" }, "locale": "cs", "paidAt": "2026-10-18T12:00:00+00:00", "accessUntil": "2027-10-18T12:00:00+00:00" } } } } } }, "404": { "description": "No report has this token (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "not_found", "message": "No building report has this token." } } } } } }, "429": { "description": "Too many reads with this report's token in a minute (`rate_limited`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "rate_limited", "message": "Too many requests; retry after 30 seconds." } } } } } } } } }, "/public/building-reports/{token}/engine/{path}": { "get": { "tags": [ "Building reports" ], "operationId": "getBuildingReportEngineRead", "summary": "A report's building record", "security": [], "description": "One record of the report's building, as a workspace that opened it reads it, without a credit: its row (`buildings/search?key={id}`, that key alone, marked `locked: false`), solar figures (`buildings/{id}/solar`), addresses (`buildings/{id}/addresses`), registered businesses (`buildings/{id}/registered-companies`), 3D model (`buildings/{id}/model3d`), register record (`v2/buildings/{id}/register`), the panel detection's photo (`buildings/{id}/solar-panel-detection/proof.jpg`, a JPEG) and the progress of its roof analysis (`buildings/{id}/solar/analysis/stream`, an event stream). Anything else is refused. Limited per report: 240 reads a minute with one token, the report's order included.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The report's token: 43 base64url characters, from the report's link (`https://app.baseray.ai/report/{token}`).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "example": "qJ3x9Yb0t2Wc5nVh8kLmZpR4sT6uE1aD7fG0hJ2kL9w" }, { "name": "path", "in": "path", "required": true, "description": "The building route, with the report's building's id where it carries one.", "schema": { "type": "string" }, "example": "buildings/c9eefd1b-8c8d-48fe-8b72-e015374d7720/registered-companies" } ], "responses": { "200": { "description": "The engine's answer as a workspace that opened the building reads it at `/api/teams/{team}/baseray/engine/{path}`: JSON, the roof analysis's event stream, or the proof photo (JPEG)." }, "403": { "description": "Not about the report's building (`route_forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "route_forbidden", "message": "A building report reads only its own building." } } } } } }, "404": { "description": "No report has this token (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "not_found", "message": "No building report has this token." } } } } } }, "409": { "description": "The report is not paid: its Checkout is still open or closed unpaid (`report_not_paid`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "report_not_paid", "message": "This report is not paid." } } } } } }, "410": { "description": "The report's access has ended (`report_access_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "report_access_expired", "message": "This report's access has ended." } } } } } }, "429": { "description": "Too many reads with this report's token in a minute (`rate_limited`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "rate_limited", "message": "Too many requests; retry after 30 seconds." } } } } } } } }, "post": { "tags": [ "Building reports" ], "operationId": "startBuildingReportRoofAnalysis", "summary": "Start a report's roof analysis", "security": [], "description": "Starts the roof analysis of the report's building (`buildings/{id}/solar/analysis`), as a workspace that opened it starts it, without a credit; follow it with `GET …/engine/buildings/{id}/solar/analysis/stream`. A report includes one run a workspace would be charged a credit for: a second start answers `409 report_analysis_used` without reaching the provider. A start that joins a run already in flight, a run no billable provider answers, or an engine that fails does not use it. Limited per report: 240 requests a minute with one token.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The report's token: 43 base64url characters, from the report's link (`https://app.baseray.ai/report/{token}`).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "example": "qJ3x9Yb0t2Wc5nVh8kLmZpR4sT6uE1aD7fG0hJ2kL9w" }, { "name": "path", "in": "path", "required": true, "description": "The building route, with the report's building's id where it carries one.", "schema": { "type": "string" }, "example": "buildings/c9eefd1b-8c8d-48fe-8b72-e015374d7720/solar/analysis" } ], "responses": { "200": { "description": "The engine's answer as a workspace reads it: `{building_id, running, started, provider, stream_url, …}`." }, "403": { "description": "Not about the report's building (`route_forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "route_forbidden", "message": "A building report reads only its own building." } } } } } }, "404": { "description": "No report has this token (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "not_found", "message": "No building report has this token." } } } } } }, "409": { "description": "The report is not paid (`report_not_paid`), or it already ran its roof analysis (`report_analysis_used`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "unpaid": { "value": { "code": "report_not_paid", "message": "This report is not paid." } }, "used": { "value": { "code": "report_analysis_used", "message": "This report already ran its roof analysis; its results stay in the report." } } } } } }, "410": { "description": "The report's access has ended (`report_access_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "report_access_expired", "message": "This report's access has ended." } } } } } }, "429": { "description": "Too many reads with this report's token in a minute (`rate_limited`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildingReportError" }, "examples": { "example": { "value": { "code": "rate_limited", "message": "Too many requests; retry after 30 seconds." } } } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "br_live_…", "description": "A workspace API key, created in the baseray app under Settings → API keys. Send it as `Authorization: Bearer br_live_…`." } }, "headers": { "RateLimit-Limit": { "description": "Requests this key may make per minute.", "schema": { "type": "integer" }, "example": 60 }, "RateLimit-Remaining": { "description": "Requests this key has left in the current minute.", "schema": { "type": "integer" }, "example": 59 }, "RateLimit-Reset": { "description": "Seconds until the current minute window resets.", "schema": { "type": "integer" }, "example": 60 }, "X-Daily-Quota-Limit": { "description": "Requests the workspace's keys may make per UTC day.", "schema": { "type": "integer" }, "example": 5000 }, "X-Daily-Quota-Remaining": { "description": "Requests the workspace has left today (UTC).", "schema": { "type": "integer" }, "example": 4868 }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" }, "example": 30 }, "Public-Cache-Control": { "description": "How long shared caches may keep the answer: a day (`public, max-age=86400, stale-while-revalidate=604800`); address search an hour (`public, max-age=3600, stale-while-revalidate=86400`); a building's preview image a week (`public, max-age=604800, stale-while-revalidate=604800`). Refusals and a moved page: an hour for 301, 400 and 404, `no-store` for 429 and 503.", "schema": { "type": "string" } }, "X-Credits-Charged": { "description": "Credits this request used: one per building in the answer that the workspace had not opened in the last 365 days. 0 when every building was already open.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Credits the workspace has left in its current monthly period, after this request.", "schema": { "type": "integer", "minimum": 0 } } }, "responses": { "InvalidParameter": { "description": "A parameter is missing, malformed or out of range (`invalid_parameter`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "bbox": { "value": { "error": { "code": "invalid_parameter", "message": "bbox must be minLon,minLat,maxLon,maxLat.", "parameter": "bbox" } } } } } } }, "Unauthenticated": { "description": "No API key, or one that does not work: `missing_api_key`, `invalid_api_key`, `revoked_api_key` or `expired_api_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "error": { "code": "missing_api_key", "message": "Send a workspace API key in the Authorization header: Bearer br_live_…." } } }, "revoked": { "value": { "error": { "code": "revoked_api_key", "message": "This API key was revoked. Create a new one under Settings → API keys." } } } } } } }, "Forbidden": { "description": "The key may not do this: `insufficient_scope`, or `workspace_access_revoked` when the key's creator no longer belongs to its workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "workspace": { "value": { "error": { "code": "workspace_access_revoked", "message": "The person who created this API key no longer belongs to its workspace." } } } } } } }, "NotFound": { "description": "No building has this id (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "building": { "value": { "error": { "code": "not_found", "message": "No building has this id." } } } } } } }, "TooManyRequests": { "description": "`rate_limited` (the key's per-minute limit) or `quota_exceeded` (the workspace's daily quota).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Daily-Quota-Limit": { "$ref": "#/components/headers/X-Daily-Quota-Limit" }, "X-Daily-Quota-Remaining": { "$ref": "#/components/headers/X-Daily-Quota-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate": { "value": { "error": { "code": "rate_limited", "message": "This API key made more than 60 requests in a minute; retry after 12 seconds." } } }, "quota": { "value": { "error": { "code": "quota_exceeded", "message": "This workspace has used its daily quota of 5000 requests; it resets at 00:00 UTC." } } } } } } }, "UpstreamUnavailable": { "description": "The building catalogue is unavailable right now (`upstream_unavailable`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream": { "value": { "error": { "code": "upstream_unavailable", "message": "The building catalogue is unavailable right now. Retry shortly." } } } } } } }, "PublicInvalidParameter": { "description": "A query parameter is missing or malformed (`invalid_parameter`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "examples": { "example": { "value": { "error": "invalid_parameter", "message": "country must be cz or ro." } } } } } }, "PublicNotFound": { "description": "No such page (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "examples": { "example": { "value": { "error": "not_found" } } } } } }, "PublicRateLimited": { "description": "Too many requests from this address in a minute (`rate_limited`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "examples": { "example": { "value": { "error": "rate_limited" } } } } } }, "PublicUnavailable": { "description": "The building catalogue is unavailable right now (`unavailable`); retry after `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicError" }, "examples": { "example": { "value": { "error": "unavailable" } } } } } }, "PaymentRequired": { "description": "`insufficient_credits`: the answer's buildings need more credits than the workspace has left this month. Nothing was returned or charged.", "headers": { "X-Credits-Charged": { "$ref": "#/components/headers/X-Credits-Charged" }, "X-Credits-Remaining": { "$ref": "#/components/headers/X-Credits-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_credits", "message": "This answer has 20 building(s) this workspace has not opened in the last 365 days, and it has 5 credit(s) left until 2026-11-01T00:00:00+00:00. Each building costs 1 credit once, then stays free for 365 days. Upgrade at https://app.baseray.ai/billing." } } } } } }, "schemas": { "Height": { "type": "object", "required": [ "metres", "basis" ], "additionalProperties": false, "properties": { "metres": { "type": "number", "description": "Height in metres.", "example": 18.0 }, "basis": { "type": "string", "enum": [ "measured", "stated", "estimated" ], "description": "`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)." } } }, "FloorArea": { "type": "object", "required": [ "square_metres", "basis", "scope" ], "additionalProperties": false, "description": "The building's floor area as best known: the figure a record states for the building where one holds, otherwise an estimate.", "properties": { "square_metres": { "type": "number", "description": "Floor area, in m²." }, "basis": { "type": [ "string", "null" ], "enum": [ "measured", "stated", "estimated", null ], "description": "`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": { "type": [ "string", "null" ], "enum": [ "gross_whole_building", "net_whole_building", "gross_full_storeys", "gross_above_ground", null ], "description": "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." } }, "example": { "square_metres": 500032.0, "basis": "estimated", "scope": "gross_above_ground" } }, "ExistingSolarPanels": { "type": "object", "required": [ "status", "photo_date", "confidence", "analysed_on", "photo_resolution_cm" ], "additionalProperties": false, "description": "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.", "properties": { "status": { "type": "string", "enum": [ "detected", "none_seen", "unclear", "not_checked" ], "description": "`detected`, `none_seen`, `unclear`, or `not_checked` (never checked, or the photo was too coarse to check)." }, "photo_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the photo checked; null when undated or never checked." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "The check's confidence in its result, 0 to 1; null when not checked." }, "analysed_on": { "type": [ "string", "null" ], "format": "date", "description": "The day the photo was checked for panels; null when never checked." }, "photo_resolution_cm": { "type": [ "number", "null" ], "minimum": 0, "description": "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." } }, "example": { "status": "none_seen", "photo_date": "2022-09-08", "confidence": 0.988, "analysed_on": "2026-09-24", "photo_resolution_cm": 30.0 } }, "RegisteredSolar": { "type": "object", "required": [ "installation_count", "installed_power_kw", "export_power_kw", "storage_capacity_kwh", "has_storage", "first_connected_on", "latest_connected_on", "first_connected_year", "latest_connected_year", "address_building_count", "shares_address", "kinds", "reported_through" ], "additionalProperties": false, "description": "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.", "properties": { "installation_count": { "type": "integer", "minimum": 1, "description": "Installations registered at the address." }, "installed_power_kw": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "Installed power in kW: the installations' sum where every one states its own, null otherwise, never a partial sum." }, "export_power_kw": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "Power approved to feed the grid, in kW: the installations' sum where every one states its own, null otherwise." }, "storage_capacity_kwh": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "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": { "type": [ "boolean", "null" ], "description": "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": { "type": [ "string", "null" ], "format": "date", "description": "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": { "type": [ "string", "null" ], "format": "date", "description": "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": { "type": [ "integer", "null" ], "description": "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.", "example": 2024 }, "latest_connected_year": { "type": [ "integer", "null" ], "description": "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": { "type": "integer", "minimum": 1, "description": "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": { "type": "boolean", "description": "True when `address_building_count` is above 1: the register then does not say which of the buildings carries the panels." }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "grid_connection", "generation_licence", "establishment_year" ] }, "uniqueItems": true, "description": "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": { "type": "string", "format": "date", "description": "The last day of the latest month the registers report: an installation entered after it is not yet listed." } }, "example": { "installation_count": 1, "installed_power_kw": 6.0, "export_power_kw": 5.88, "storage_capacity_kwh": 4.8, "has_storage": true, "first_connected_on": "2024-03-01", "latest_connected_on": "2024-03-01", "first_connected_year": 2024, "latest_connected_year": 2024, "address_building_count": 1, "shares_address": false, "kinds": [ "grid_connection" ], "reported_through": "2026-07-31" } }, "SolarPotential": { "type": "object", "required": [ "max_panel_count", "max_capacity_kwp", "yearly_energy_kwh", "usable_roof_area_m2", "co2_savings_kg_per_year", "basis" ], "additionalProperties": false, "description": "Rooftop solar potential, present only where the roof has been modelled.", "properties": { "max_panel_count": { "type": [ "integer", "null" ], "description": "Solar panels that fit on the roof." }, "max_capacity_kwp": { "type": [ "number", "null" ], "description": "Capacity of those panels, in kWp." }, "yearly_energy_kwh": { "type": [ "number", "null" ], "description": "Energy they would produce in a year, in kWh." }, "usable_roof_area_m2": { "type": [ "number", "null" ], "description": "Roof area usable for panels, in m²." }, "co2_savings_kg_per_year": { "type": [ "number", "null" ], "description": "CO₂ the installation would save, in kg a year." }, "basis": { "type": [ "string", "null" ], "enum": [ "measured", "measured_cut_to_outline", "estimated", null ], "description": "`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." } }, "example": { "max_panel_count": 315, "max_capacity_kwp": 126.0, "yearly_energy_kwh": 158019.9, "usable_roof_area_m2": 618.5, "co2_savings_kg_per_year": 36976.7, "basis": "measured" } }, "StatedFact": { "type": "object", "required": [ "fact", "label", "value", "unit", "note" ], "additionalProperties": false, "description": "One thing the building's record states, as the record words it.", "properties": { "fact": { "type": "string", "description": "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`.", "example": "construction_year" }, "label": { "type": "string", "description": "The fact's name, for people.", "example": "Construction year" }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ], "description": "A number (a count, a year, or a quantity in `unit`), the record's wording, or its wordings." }, "unit": { "type": [ "string", "null" ], "description": "The unit of a quantity: `m2` or `m3`; null for counts, years and wordings." }, "note": { "type": [ "string", "null" ], "description": "How the record defines or qualifies the value; null when it adds nothing." } }, "example": { "fact": "construction_year", "label": "Construction year", "value": 1974, "unit": null, "note": null } }, "BuildingPart": { "type": "object", "required": [ "origin", "record_reference", "label", "outline_reference", "area_m2" ], "additionalProperties": false, "description": "One part a building is drawn from: a construction the national building register records, or a structure it does not record.", "properties": { "origin": { "type": "string", "enum": [ "register", "unregistered" ], "description": "`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": { "type": [ "string", "null" ], "description": "The register's own reference for the construction's record; null for a part not in the register." }, "label": { "type": [ "string", "null" ], "description": "How the register names the construction, e.g. `62847-C1`; null where it names none." }, "outline_reference": { "type": "string", "enum": [ "footprint", "roof_edge" ], "description": "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": { "type": "number", "description": "The area of the part's outline, in m²." } }, "example": { "origin": "register", "record_reference": "RV63R3-04", "label": "62847-C1", "outline_reference": "footprint", "area_m2": 117.9 } }, "Turnover": { "type": "object", "required": [ "amount", "currency", "financial_year" ], "additionalProperties": false, "description": "A turnover from a business's latest financial statement on record.", "properties": { "amount": { "type": "integer", "description": "Turnover, in whole units of `currency`." }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency of the statement." }, "financial_year": { "type": [ "integer", "null" ], "description": "The financial year of the statement." } }, "example": { "amount": 1250000, "currency": "RON", "financial_year": 2024 } }, "BuildingSummary": { "type": "object", "additionalProperties": false, "required": [ "building_id", "address", "nearest_road", "address_evidence", "address_corroboration", "postal_code", "locality", "country", "latitude", "longitude", "category", "category_evidence", "building_type", "roof_shape", "footprint_area_m2", "height", "volume_m3", "volume_basis", "floor_area", "floors", "floors_including_underground", "construction_year", "completed_by_year", "dwellings", "existing_solar_panels", "solar_presence", "registered_solar", "solar_potential", "registered_business_count", "registered_business_employees", "registered_business_turnover", "flood_zone", "flood_zone_mapped", "flood_zone_source", "seismic_design_acceleration_g", "seismic_risk_class", "seismic_risk_assessment_year", "app_url" ], "properties": { "building_id": { "type": "string", "format": "uuid", "description": "The building's baseray id." }, "address": { "type": [ "string", "null" ], "description": "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": { "type": [ "string", "null" ], "description": "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.", "example": "Strada Principală" }, "address_evidence": { "type": [ "string", "null" ], "enum": [ "address_record", "business_listing", null ], "description": "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": { "type": [ "string", "null" ], "enum": [ "corroborated", "single_source", "conflicting", null ], "description": "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": { "type": [ "string", "null" ], "description": "The official postcode of the building's address; null when none is on record." }, "locality": { "type": [ "string", "null" ], "description": "Town, city or village." }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code." }, "latitude": { "type": "number", "description": "Latitude of the building's centre, WGS84." }, "longitude": { "type": "number", "description": "Longitude of the building's centre, WGS84." }, "category": { "type": "string", "enum": [ "residential_house", "apartment_block", "commercial", "industrial", "public", "agricultural", "ancillary", "unknown" ], "description": "Building category; `ancillary` is an annex or outbuilding." }, "category_evidence": { "type": "string", "enum": [ "confirmed", "corroborated", "inferred", "conflicting", "unconfirmed" ], "description": "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": { "type": [ "string", "null" ], "description": "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.", "example": "office" }, "roof_shape": { "type": [ "string", "null" ], "description": "The roof's shape, as the `roof_shape` filter reads it, e.g. `gabled`, `hipped`, `flat`; null when unknown.", "example": "flat" }, "footprint_area_m2": { "type": "number", "description": "Ground footprint, in m²." }, "height": { "oneOf": [ { "$ref": "#/components/schemas/Height" }, { "type": "null" } ], "description": "Height; null when unknown." }, "volume_m3": { "type": [ "number", "null" ], "description": "Volume, in m³; null when unknown." }, "volume_basis": { "type": [ "string", "null" ], "enum": [ "measured", "estimated", null ], "description": "Whether the volume is measured or estimated; null with the volume." }, "floor_area": { "oneOf": [ { "$ref": "#/components/schemas/FloorArea" }, { "type": "null" } ], "description": "Floor area, with what it rests on and what it counts; null when unknown." }, "floors": { "type": [ "integer", "null" ], "description": "Floors above ground; null when unknown." }, "floors_including_underground": { "type": [ "integer", "null" ], "description": "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": { "type": [ "integer", "null" ], "description": "The year a register states the building was completed; null when none states it." }, "completed_by_year": { "type": [ "integer", "null" ], "description": "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": { "type": [ "integer", "null" ], "description": "Dwellings, where known; null when unknown." }, "existing_solar_panels": { "$ref": "#/components/schemas/ExistingSolarPanels" }, "solar_presence": { "type": "string", "enum": [ "registered", "detected", "registered_at_address", "none_seen", "unclear", "unknown" ], "description": "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.", "example": "registered" }, "registered_solar": { "oneOf": [ { "$ref": "#/components/schemas/RegisteredSolar" }, { "type": "null" } ], "description": "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." }, "solar_potential": { "oneOf": [ { "$ref": "#/components/schemas/SolarPotential" }, { "type": "null" } ], "description": "Rooftop solar potential; null where the roof has not been modelled." }, "registered_business_count": { "type": "integer", "minimum": 0, "description": "Active businesses whose registered office is the building's address. Never ownership or occupancy." }, "registered_business_employees": { "type": [ "string", "null" ], "description": "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.", "example": "10–49" }, "registered_business_turnover": { "oneOf": [ { "$ref": "#/components/schemas/Turnover" }, { "type": "null" } ], "description": "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." }, "flood_zone": { "type": [ "string", "null" ], "enum": [ "5_year", "10_year", "20_year", "50_year", "100_year", "100_year_climate_change", "500_year", "1000_year", "10000_year", null ], "description": "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.", "example": "100_year" }, "flood_zone_mapped": { "type": "boolean", "description": "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": { "type": [ "string", "null" ], "description": "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": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "description": "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.", "example": 0.3 }, "seismic_risk_class": { "type": [ "string", "null" ], "enum": [ "RsI", "RsII", "RsIII", "RsIV", "U1", "U2", "U3", "consolidated", null ], "description": "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.", "example": "RsI" }, "seismic_risk_assessment_year": { "type": [ "integer", "null" ], "description": "The year of the assessment that set `seismic_risk_class`; null when not stated.", "example": 2016 }, "app_url": { "type": "string", "format": "uri", "description": "The building in the baseray app." } }, "example": { "building_id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "address": "Bulevardul 15 Noiembrie 78", "nearest_road": null, "address_evidence": "address_record", "address_corroboration": "single_source", "postal_code": null, "locality": "Brașov", "country": "RO", "latitude": 45.64988, "longitude": 25.61044, "category": "commercial", "category_evidence": "confirmed", "building_type": "retail", "roof_shape": "flat", "footprint_area_m2": 31252.0, "height": { "metres": 18.0, "basis": "estimated" }, "volume_m3": 562531.0, "volume_basis": "estimated", "floor_area": { "square_metres": 500032.0, "basis": "estimated", "scope": "gross_above_ground" }, "floors": 16, "floors_including_underground": null, "construction_year": null, "completed_by_year": null, "dwellings": null, "existing_solar_panels": { "status": "none_seen", "photo_date": "2022-09-08", "confidence": 0.988, "analysed_on": null, "photo_resolution_cm": null }, "solar_presence": "none_seen", "registered_solar": null, "solar_potential": null, "registered_business_count": 0, "registered_business_employees": null, "registered_business_turnover": null, "flood_zone": null, "flood_zone_mapped": false, "flood_zone_source": null, "seismic_design_acceleration_g": null, "seismic_risk_class": null, "seismic_risk_assessment_year": null, "app_url": "https://app.baseray.ai/?building=c9eefd1b-8c8d-48fe-8b72-e015374d7720" } }, "BuildingDetail": { "allOf": [ { "$ref": "#/components/schemas/BuildingSummary" }, { "type": "object", "required": [ "entrances", "stated_facts", "is_current", "replaced_by_building_id", "outline_reference", "parts", "eave_height_m", "has_3d_model", "addresses", "units", "record_sheet", "roof_analysis", "climate", "energy_networks", "heating_estimate" ], "properties": { "entrances": { "type": [ "integer", "null" ], "description": "Entrances: each listed address of the building counts as one; null when none are listed." }, "stated_facts": { "type": "array", "items": { "$ref": "#/components/schemas/StatedFact" }, "description": "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`." }, "is_current": { "type": "boolean", "description": "False once the building is no longer in the catalogue's current release." }, "replaced_by_building_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The building now standing on a retired building's ground, when there is one." }, "outline_reference": { "type": [ "string", "null" ], "enum": [ "footprint", "roof_edge", "combined", null ], "description": "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": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingPart" }, "description": "The parts the building is drawn from, register parts first, then the largest; empty where it is not drawn from parts." }, "eave_height_m": { "type": [ "number", "null" ], "minimum": 0, "description": "The height of the eaves; null when unknown." }, "has_3d_model": { "type": [ "boolean", "null" ], "description": "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": { "oneOf": [ { "$ref": "#/components/schemas/BuildingAddresses" }, { "type": "null" } ], "description": "Every address of the building, each entrance with the dwellings behind it; null when none is on record." }, "units": { "oneOf": [ { "$ref": "#/components/schemas/UnitsSummary" }, { "type": "null" } ], "description": "What the building's record says of its units; null when it neither lists units nor states how many there are." }, "record_sheet": { "oneOf": [ { "$ref": "#/components/schemas/RecordSheet" }, { "type": "null" } ], "description": "The building's whole record as its register lays it out; null when no register record is on file." }, "roof_analysis": { "oneOf": [ { "$ref": "#/components/schemas/RoofAnalysis" }, { "type": "null" } ], "description": "The roof analysis behind `solar_potential`, plane by plane; null when the roof has not been analysed." }, "climate": { "oneOf": [ { "$ref": "#/components/schemas/Climate" }, { "type": "null" } ], "description": "The local climate; null when none is on record." }, "energy_networks": { "type": "array", "items": { "$ref": "#/components/schemas/EnergyNetworkLevel" }, "description": "Gas and district-heating network evidence from the locality down to the building; empty when none is on record." }, "heating_estimate": { "oneOf": [ { "$ref": "#/components/schemas/HeatingEstimate" }, { "type": "null" } ], "description": "The heating estimate, a model estimate; null when the building is not modelled." } } } ], "unevaluatedProperties": false, "example": { "building_id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "address": "Bulevardul 15 Noiembrie 78", "nearest_road": null, "address_evidence": "address_record", "address_corroboration": "single_source", "postal_code": null, "locality": "Brașov", "country": "RO", "latitude": 45.64988, "longitude": 25.61044, "category": "commercial", "category_evidence": "confirmed", "building_type": "retail", "roof_shape": "flat", "footprint_area_m2": 31252.0, "height": { "metres": 18.0, "basis": "estimated" }, "volume_m3": 562531.0, "volume_basis": "estimated", "floor_area": { "square_metres": 500032.0, "basis": "estimated", "scope": "gross_above_ground" }, "floors": 16, "floors_including_underground": null, "construction_year": null, "completed_by_year": null, "dwellings": null, "existing_solar_panels": { "status": "none_seen", "photo_date": "2022-09-08", "confidence": 0.988, "analysed_on": null, "photo_resolution_cm": null }, "solar_presence": "none_seen", "registered_solar": null, "solar_potential": null, "registered_business_count": 0, "registered_business_employees": null, "registered_business_turnover": null, "flood_zone": null, "flood_zone_mapped": false, "flood_zone_source": null, "seismic_design_acceleration_g": null, "seismic_risk_class": null, "seismic_risk_assessment_year": null, "app_url": "https://app.baseray.ai/?building=c9eefd1b-8c8d-48fe-8b72-e015374d7720", "entrances": null, "stated_facts": [], "is_current": true, "replaced_by_building_id": null, "outline_reference": null, "parts": [], "eave_height_m": null, "has_3d_model": null, "addresses": null, "units": null, "record_sheet": null, "roof_analysis": null, "climate": null, "energy_networks": [], "heating_estimate": null } }, "RegisteredBusiness": { "type": "object", "required": [ "name", "registration_number", "country", "employees", "employees_stated_for", "advertising_protected", "natural_person", "legal_form", "person_kind", "ceased_on" ], "additionalProperties": false, "description": "Registered office at this address; never ownership or occupancy.", "properties": { "name": { "type": "string", "description": "The business's registered name." }, "registration_number": { "type": "string", "description": "Its company registration number (a CUI in Romania, an IČO in Czechia, a CVR number in Denmark)." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country of the registration number." }, "employees": { "type": [ "string", "null" ], "description": "Employees as stated: an exact count (`12`), a band (`10–49`) or an open top band (`1000 or more`); null when not stated.", "example": "10–49" }, "employees_stated_for": { "type": [ "string", "null" ], "description": "When the size was stated: a date, or a financial year such as `FY 2024`.", "example": "FY 2024" }, "advertising_protected": { "type": [ "boolean", "null" ], "description": "True where the business's register protects it from direct marketing (in Denmark, reklamebeskyttelse under CVR-loven § 19: \"Reklamebeskyttet – må ikke bruges til direkte markedsføring\"): its data may not be used for direct marketing and may be passed on only marked as protected. False where the register states it unprotected; null where the register states nothing of the kind.", "example": false }, "natural_person": { "type": [ "boolean", "null" ], "description": "True where the register's legal form makes the business a person's: a sole proprietorship or personally owned small business, or the estate of a deceased person. Its name is then usually its owner's. Null where the register states no legal form.", "example": false }, "legal_form": { "oneOf": [ { "type": "object", "required": [ "code", "label" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "The register's code for the form.", "example": "80" }, "label": { "type": "string", "description": "The form in the register's own words.", "example": "Anpartsselskab" } } }, { "type": "null" } ], "description": "The legal form as the register codes and words it; null where it states none." }, "person_kind": { "type": [ "string", "null" ], "enum": [ "personally_owned", "estate", null ], "description": "For a person's business: `personally_owned` (\"Personligt ejet virksomhed\": a sole proprietorship or personally owned small business) or `estate` (\"Dødsbo\": the estate of a deceased person). Null for any other business." }, "ceased_on": { "type": [ "string", "null" ], "format": "date", "description": "The day a person's business ceased, given only for one still served after it ceased (\"Ophørt\"); null while it is active." } } }, "PaginationMeta": { "type": "object", "required": [ "total", "total_is_capped", "limit", "offset", "sort" ], "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0, "description": "Buildings matching, counted up to 10,000." }, "total_is_capped": { "type": "boolean", "description": "True when counting stopped at 10,000; narrow the box for an exact total." }, "limit": { "type": "integer", "description": "The page size used." }, "offset": { "type": "integer", "description": "The offset used." }, "sort": { "type": "string", "enum": [ "volume", "area", "height", "registered_business_turnover", "registered_business_employees" ], "description": "The ranking used." } } }, "Links": { "type": "object", "required": [ "next" ], "additionalProperties": false, "properties": { "next": { "type": [ "string", "null" ], "format": "uri", "description": "The next page's URL; null on the last page." } } }, "BuildingPage": { "type": "object", "required": [ "data", "meta", "links" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingSummary" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "links": { "$ref": "#/components/schemas/Links" } } }, "BuildingList": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingSummary" }, "description": "Nearest first." } } }, "BuildingDetailEnvelope": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BuildingDetail" } } }, "RegisteredBusinessList": { "type": "object", "required": [ "data", "meta" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegisteredBusiness" }, "maxItems": 25 }, "meta": { "type": "object", "required": [ "total", "sources" ], "additionalProperties": false, "properties": { "total": { "type": "integer", "minimum": 0, "description": "Every business registered at the address; can exceed the businesses listed." }, "sources": { "type": "array", "items": { "type": "string" }, "description": "The credits the registers of the businesses listed require wherever their data are passed on, such as \"Indeholder data fra Det Centrale Virksomhedsregister (CVR), Erhvervsstyrelsen, via Datafordeleren (CC BY 4.0)\". Empty when none is required." } } } } }, "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "missing_api_key", "invalid_api_key", "revoked_api_key", "expired_api_key", "insufficient_scope", "workspace_access_revoked", "not_found", "rate_limited", "quota_exceeded", "insufficient_credits", "upstream_unavailable" ], "description": "Stable machine-readable reason." }, "message": { "type": "string", "description": "What went wrong, for people." }, "parameter": { "type": "string", "description": "The parameter at fault, for `invalid_parameter`." } } } }, "example": { "error": { "code": "invalid_parameter", "message": "bbox must be minLon,minLat,maxLon,maxLat.", "parameter": "bbox" } } }, "PublicError": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "string", "enum": [ "not_found", "invalid_parameter", "rate_limited", "unavailable" ], "description": "Stable machine-readable reason." }, "message": { "type": "string", "description": "What is wrong with the parameter, for `invalid_parameter`." } }, "description": "The body of every refusal (4xx and 5xx) of the public building pages.", "example": { "error": "not_found" } }, "PublicBuildingAddress": { "type": "object", "required": [ "street", "number", "locality", "district", "county", "postcode", "label" ], "additionalProperties": false, "properties": { "street": { "type": [ "string", "null" ], "description": "Street name; null for a village address without streets." }, "number": { "type": [ "string", "null" ], "description": "House number as the address record writes it." }, "locality": { "type": [ "string", "null" ], "description": "Town or village." }, "district": { "type": [ "string", "null" ], "description": "City district or sector, where the place has them." }, "county": { "type": [ "string", "null" ], "description": "County (Romanian județ, Czech kraj)." }, "postcode": { "type": [ "string", "null" ], "description": "Postcode; null when none is on record." }, "label": { "type": "string", "description": "The full address on one line, as it is written locally." } }, "description": "The building's address, from an address record." }, "PublicUseFact": { "type": "object", "required": [ "value", "label", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "string", "null" ], "description": "Use code, e.g. `residential_multi`; null when unknown." }, "label": { "type": [ "string", "null" ], "description": "The use in the country's own words, e.g. `Bytový dům`." }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicFloorsFact": { "type": "object", "required": [ "value", "estimate", "includesUnderground" ], "additionalProperties": false, "properties": { "value": { "type": [ "integer", "null" ], "description": "Floors; null when unknown." }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." }, "includesUnderground": { "type": "boolean", "description": "True when the count includes floors below ground." } } }, "PublicBuiltFact": { "type": "object", "required": [ "year", "era", "estimate" ], "additionalProperties": false, "properties": { "year": { "type": [ "integer", "null" ], "description": "Year of completion; null when only the era is known or nothing is." }, "era": { "type": [ "string", "null" ], "description": "The period it was built in, e.g. `1919–1945`, where the record gives a period rather than a year." }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicAreaFact": { "type": "object", "required": [ "value", "unit", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "number", "null" ], "description": "Area in m²; null when unknown." }, "unit": { "type": "string", "enum": [ "m2" ] }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicFloorAreaFact": { "type": "object", "required": [ "value", "unit", "scope", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "number", "null" ], "description": "Floor area in m²; null when unknown." }, "unit": { "type": "string", "enum": [ "m2" ] }, "scope": { "type": [ "string", "null" ], "enum": [ "usable", "gross", null ], "description": "`usable` (the usable floor area) or `gross` (the built floor area); null when unknown." }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicHeightFact": { "type": "object", "required": [ "value", "unit", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "number", "null" ], "description": "Height in metres; null when unknown." }, "unit": { "type": "string", "enum": [ "m" ] }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicVolumeFact": { "type": "object", "required": [ "value", "unit", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "number", "null" ], "description": "Volume in m³; null when unknown." }, "unit": { "type": "string", "enum": [ "m3" ] }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicTextFact": { "type": "object", "required": [ "value", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "string", "null" ], "description": "The value; null when unknown." }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicCountFact": { "type": "object", "required": [ "value", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": [ "integer", "null" ], "description": "The count; null when unknown." }, "estimate": { "type": "boolean", "description": "True when the value is modelled rather than taken from a record or a measurement." } } }, "PublicFloodZone": { "type": "object", "required": [ "value", "estimate" ], "additionalProperties": false, "properties": { "value": { "type": "string", "description": "The flood zone the building lies in." }, "estimate": { "type": "boolean", "enum": [ false ], "description": "Always false: the value is taken from an official map." } } }, "PublicSeismicZone": { "type": "object", "required": [ "designAccelerationG", "estimate" ], "additionalProperties": false, "properties": { "designAccelerationG": { "type": "number", "description": "The design ground acceleration of the building's seismic zone, in g." }, "estimate": { "type": "boolean", "enum": [ false ], "description": "Always false: the value is taken from an official map." } } }, "PublicCadastralReference": { "type": "object", "required": [ "value", "officialUrl" ], "additionalProperties": false, "properties": { "value": { "type": "string", "description": "The building's number in the national register." }, "officialUrl": { "type": [ "string", "null" ], "description": "The register's own public page for the building, where it has one." } } }, "PublicBuildingFacts": { "type": "object", "required": [ "use", "floors", "built", "footprintArea", "floorArea", "height", "volume", "roofArea", "roofShape", "dwellings", "floodZone", "seismicZone", "cadastralRef" ], "additionalProperties": false, "properties": { "use": { "oneOf": [ { "$ref": "#/components/schemas/PublicUseFact" }, { "type": "null" } ], "description": "What the building is used for." }, "floors": { "oneOf": [ { "$ref": "#/components/schemas/PublicFloorsFact" }, { "type": "null" } ], "description": "Floors." }, "built": { "oneOf": [ { "$ref": "#/components/schemas/PublicBuiltFact" }, { "type": "null" } ], "description": "When it was built." }, "footprintArea": { "oneOf": [ { "$ref": "#/components/schemas/PublicAreaFact" }, { "type": "null" } ], "description": "Area of the building's footprint." }, "floorArea": { "oneOf": [ { "$ref": "#/components/schemas/PublicFloorAreaFact" }, { "type": "null" } ], "description": "Floor area." }, "height": { "oneOf": [ { "$ref": "#/components/schemas/PublicHeightFact" }, { "type": "null" } ], "description": "Height." }, "volume": { "oneOf": [ { "$ref": "#/components/schemas/PublicVolumeFact" }, { "type": "null" } ], "description": "Volume above ground." }, "roofArea": { "oneOf": [ { "$ref": "#/components/schemas/PublicAreaFact" }, { "type": "null" } ], "description": "Roof area." }, "roofShape": { "oneOf": [ { "$ref": "#/components/schemas/PublicTextFact" }, { "type": "null" } ], "description": "Roof shape, e.g. `flat` or `gabled`." }, "dwellings": { "oneOf": [ { "$ref": "#/components/schemas/PublicCountFact" }, { "type": "null" } ], "description": "Dwellings." }, "floodZone": { "oneOf": [ { "$ref": "#/components/schemas/PublicFloodZone" }, { "type": "null" } ], "description": "The flood zone; null when the building lies in none on record or it is unknown." }, "seismicZone": { "oneOf": [ { "$ref": "#/components/schemas/PublicSeismicZone" }, { "type": "null" } ], "description": "The seismic zone; null where the country has no seismic zoning on record." }, "cadastralRef": { "oneOf": [ { "$ref": "#/components/schemas/PublicCadastralReference" }, { "type": "null" } ], "description": "The building's number in the national register." } }, "description": "Each fact is its value or `null` (unknown, never zero), and says whether it is an estimate." }, "PublicPolygon": { "type": "object", "required": [ "type", "coordinates" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "Polygon" ] }, "coordinates": { "type": "array", "description": "GeoJSON rings of `[longitude, latitude]` positions in WGS84; the first ring is the outline, any further ones holes.", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } } }, "description": "The building's outline as a GeoJSON Polygon." }, "PublicBuildingContext": { "type": "object", "required": [ "streetBuildings", "olderThanShareOnStreet", "tallerThanShareInLocality" ], "additionalProperties": false, "properties": { "streetBuildings": { "type": [ "integer", "null" ], "description": "Buildings on the same street." }, "olderThanShareOnStreet": { "type": [ "number", "null" ], "description": "Share (0–1) of the street's buildings with a known age that this building is older than." }, "tallerThanShareInLocality": { "type": [ "number", "null" ], "description": "Share (0–1) of the locality's buildings with a known height that this building is taller than." } }, "description": "How the building compares with its street and locality; null where too little is known." }, "PublicPlaceReference": { "type": "object", "required": [ "country", "slug", "name" ], "additionalProperties": false, "properties": { "country": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "slug": { "type": "string", "description": "The place's slug, for `/public/places/{country}/{slug}/stats`." }, "name": { "type": "string", "description": "The place's name." } } }, "PublicGatedCounts": { "type": "object", "required": [ "solarChecked", "registeredCompanies" ], "additionalProperties": false, "properties": { "solarChecked": { "type": "boolean", "description": "True when the roof has been checked for solar panels; the verdict is shown only after signing in." }, "registeredCompanies": { "type": "integer", "description": "Companies with their registered office at the address; who they are is shown only after signing in. A registered office is not ownership." } }, "description": "What signing in shows, as counts only." }, "PublicBuilding": { "type": "object", "required": [ "id", "country", "slug", "address", "facts", "outline", "centroid", "context", "place", "gated", "updatedAt" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "description": "The building's baseray id, the same as in the rest of this API." }, "country": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "slug": { "type": "string", "description": "A readable slug for the building's page URL, from its locality and address." }, "address": { "$ref": "#/components/schemas/PublicBuildingAddress" }, "facts": { "$ref": "#/components/schemas/PublicBuildingFacts" }, "outline": { "$ref": "#/components/schemas/PublicPolygon" }, "centroid": { "type": "array", "items": { "type": "number" }, "description": "`[longitude, latitude]` of the outline's centre, WGS84." }, "context": { "$ref": "#/components/schemas/PublicBuildingContext" }, "place": { "oneOf": [ { "$ref": "#/components/schemas/PublicPlaceReference" }, { "type": "null" } ], "description": "The place whose statistics page the building belongs to; null when it belongs to none." }, "streetPage": { "oneOf": [ { "type": "object", "required": [ "slug", "name" ], "additionalProperties": false, "properties": { "slug": { "type": "string", "description": "For `/public/places/{country}/{slug}/streets/{street}`, with the place's slug." }, "name": { "type": "string" } } }, { "type": "null" } ], "description": "The page of the building's street; null where its street has none." }, "gated": { "$ref": "#/components/schemas/PublicGatedCounts" }, "updatedAt": { "type": "string", "format": "date", "description": "When the building's facts last changed." }, "street": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/PublicNeighbourBuilding" }, "description": "Other buildings with a public page on the same street of the same locality, closest house numbers first; empty without a street." }, "nearby": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/PublicNeighbourBuilding" }, "description": "The closest other buildings with a public page off that street (within about 600 m), nearest first, each with `distanceM`." }, "surroundings": { "type": "array", "maxItems": 150, "items": { "$ref": "#/components/schemas/PublicSurroundingOutline" }, "description": "Outlines of every building within about 65 m of this one, with or without a public page, nearest first." } }, "description": "One building's public facts.", "example": { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "country": "cz", "slug": "praha-vinohradska-12", "address": { "street": "Vinohradská", "number": "12", "locality": "Praha", "district": "Praha 2", "county": "Hlavní město Praha", "postcode": "12000", "label": "Vinohradská 1200/12, 120 00 Praha 2" }, "facts": { "use": { "value": "residential_multi", "label": "Bytový dům", "estimate": false }, "floors": { "value": 6, "estimate": false, "includesUnderground": false }, "built": { "year": null, "era": "1919–1945", "estimate": false }, "footprintArea": { "value": 412.5, "unit": "m2", "estimate": false }, "floorArea": { "value": null, "unit": "m2", "scope": null, "estimate": false }, "height": { "value": 21.4, "unit": "m", "estimate": false }, "volume": { "value": 8800, "unit": "m3", "estimate": true }, "roofArea": { "value": 430, "unit": "m2", "estimate": true }, "roofShape": { "value": "flat", "estimate": true }, "dwellings": { "value": 24, "estimate": false }, "floodZone": null, "seismicZone": null, "cadastralRef": { "value": "1200", "officialUrl": "https://nahlizenidokn.cuzk.cz/" } }, "outline": { "type": "Polygon", "coordinates": [ [ [ 14.4301, 50.0751 ], [ 14.4305, 50.0751 ], [ 14.4305, 50.0754 ], [ 14.4301, 50.0754 ], [ 14.4301, 50.0751 ] ] ] }, "centroid": [ 14.4303, 50.07525 ], "context": { "streetBuildings": 38, "olderThanShareOnStreet": 0.71, "tallerThanShareInLocality": 0.84 }, "place": { "country": "cz", "slug": "praha", "name": "Praha" }, "gated": { "solarChecked": true, "registeredCompanies": 3 }, "updatedAt": "2026-10-01" } }, "PublicBuildingMoved": { "type": "object", "required": [ "movedTo" ], "additionalProperties": false, "properties": { "movedTo": { "type": "object", "required": [ "id", "country", "slug" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid", "description": "The replacement's baseray id." }, "country": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "slug": { "type": "string", "description": "The replacement page's slug, as its `PublicBuilding` gives it." } }, "description": "The public page a retired building's page moved to." } }, "description": "The body of a 301: where a retired building's page moved.", "example": { "movedTo": { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "country": "cz", "slug": "praha-vinohradska-12" } } }, "PublicModel3DSource": { "type": "object", "required": [ "label", "licence", "url" ], "additionalProperties": false, "properties": { "label": { "type": "string", "description": "The open dataset the shell was measured from, as its credit names it." }, "licence": { "type": "string", "description": "The licence the dataset is published under, as people write it (`CC BY 4.0`)." }, "url": { "type": "string", "format": "uri", "description": "The publisher's page of the dataset." } }, "description": "The credit a shell measured from open data carries wherever it is drawn." }, "PublicModel3DMesh": { "type": "object", "required": [ "vertices", "faces" ], "additionalProperties": false, "properties": { "vertices": { "type": "array", "description": "`[x, y, z]` positions in metres, in the frame of `outline`.", "items": { "type": "array", "items": { "type": "number" } } }, "faces": { "type": "array", "description": "Triangles, each three indices into `vertices`.", "items": { "type": "array", "items": { "type": "integer" } } } }, "description": "A shell's roof and walls as triangles." }, "PublicBuildingModel3D": { "type": "object", "required": [ "buildingId", "kind", "heightM", "heightOnRecord", "source", "outline", "holes", "mesh" ], "additionalProperties": false, "properties": { "buildingId": { "type": "string", "format": "uuid", "description": "The building's baseray id." }, "kind": { "type": "string", "enum": [ "lod2", "extruded", "flat" ], "description": "`lod2`: a shell measured from open data, in `mesh`. `extruded`: raise `outline` to `heightM`. `flat`: draw `outline` flat; no height is known." }, "heightM": { "type": [ "number", "null" ], "description": "The height the building's public page shows, in metres; null where it shows none." }, "heightOnRecord": { "type": "boolean", "description": "False where `heightM` is an estimate, or null." }, "source": { "oneOf": [ { "$ref": "#/components/schemas/PublicModel3DSource" }, { "type": "null" } ], "description": "Set for `lod2` only." }, "outline": { "description": "The outer ring as `[x, y]` positions, counter-clockwise, without a closing position.", "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "holes": { "type": "array", "description": "Courtyards, each a clockwise ring like `outline`.", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } }, "mesh": { "oneOf": [ { "$ref": "#/components/schemas/PublicModel3DMesh" }, { "type": "null" } ], "description": "Set for `lod2` only." } }, "description": "What a building's public page draws it in 3D from. Positions are in metres about the outline's centroid at ground level (x east, y north, z up), to the centimetre.", "example": { "buildingId": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "kind": "extruded", "heightM": 21.4, "heightOnRecord": false, "source": null, "outline": [ [ -6.12, -4.05 ], [ 6.12, -4.05 ], [ 6.12, 4.05 ], [ -6.12, 4.05 ] ], "holes": [], "mesh": null } }, "PublicBuildingIndex": { "type": "object", "required": [ "items", "nextCursor", "total" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "updatedAt" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "updatedAt": { "type": "string", "format": "date" } } } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; null on the last one." }, "total": { "type": "integer", "description": "Buildings with a public page in the country." } }, "description": "One page of a country's buildings that have a public page, in a stable order.", "example": { "items": [ { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "slug": "praha-vinohradska-12", "updatedAt": "2026-10-01" } ], "nextCursor": "eyJrIjoiYzllZSJ9", "total": 2210000 } }, "PublicAddressSearchResult": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "id", "slug", "label", "indexable" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "The building's slug; its page exists only when `indexable` is true." }, "label": { "type": "string", "description": "The address on one line." }, "indexable": { "type": "boolean", "description": "True when the building has a public page; otherwise its facts are shown only after signing in." } } } } }, "description": "Up to ten addressed buildings matching the text.", "example": { "items": [ { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "slug": "praha-vinohradska-12", "label": "Vinohradská 1200/12, 120 00 Praha 2", "indexable": true } ] } }, "PublicPlaceList": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "county", "buildings", "indexableBuildings", "streets" ], "additionalProperties": false, "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "county": { "type": [ "string", "null" ] }, "buildings": { "type": "integer", "description": "Buildings in the place." }, "indexableBuildings": { "type": "integer", "description": "Of them, buildings with a public page." }, "streets": { "type": "integer", "description": "Streets of the place with their own page (0 without any)." } } } } }, "description": "Towns of at least 2,000 inhabitants or 500 buildings; in Romania municipalities, towns and Bucharest's sectors.", "example": { "items": [ { "slug": "iasi", "name": "Iași", "county": "Iași", "buildings": 61234, "indexableBuildings": 18000, "streets": 412 } ] } }, "PublicPlaceStatistics": { "type": "object", "required": [ "name", "county", "buildings", "addressed", "built", "floors", "tallest", "solar", "roofAreaTotalM2", "registeredCompanies", "updatedAt" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "county": { "type": [ "string", "null" ] }, "buildings": { "type": "integer" }, "addressed": { "type": "integer", "description": "Buildings with an address from an address record." }, "built": { "type": "object", "required": [ "known", "byEra", "before1978Share" ], "additionalProperties": false, "properties": { "known": { "type": "integer", "description": "Buildings whose construction year or era is known." }, "byEra": { "type": "array", "items": { "type": "object", "required": [ "era", "count" ], "additionalProperties": false, "properties": { "era": { "type": "string" }, "count": { "type": "integer" } } } }, "before1978Share": { "type": [ "number", "null" ], "description": "Share (0–1) of buildings with a known year built before 1978." } } }, "floors": { "type": "object", "required": [ "known", "histogram", "blocks4plus" ], "additionalProperties": false, "properties": { "known": { "type": "integer", "description": "Buildings whose floors are known." }, "histogram": { "type": "array", "items": { "type": "object", "required": [ "floors", "count" ], "additionalProperties": false, "properties": { "floors": { "type": "string", "description": "A floor count or a range, e.g. `1` or `10+`." }, "count": { "type": "integer" } } } }, "blocks4plus": { "type": "integer", "description": "Buildings of four or more floors." } } }, "tallest": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "height", "label" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "height": { "type": [ "number", "null" ], "description": "Height in metres; null where the building is ranked by its floors because no height is measured." }, "label": { "type": "string" } } } }, "solar": { "oneOf": [ { "type": "object", "required": [ "checkedRoofs", "withPanels", "imageryYears" ], "additionalProperties": false, "properties": { "checkedRoofs": { "type": "integer", "description": "Roofs checked for solar panels." }, "withPanels": { "type": "integer", "description": "Of them, roofs with panels." }, "imageryYears": { "type": "array", "items": { "type": "integer" }, "description": "Years of the photos the roofs were checked on." } } }, { "type": "null" } ], "description": "Rooftop solar counts; null where no roof in the place has been checked." }, "roofAreaTotalM2": { "type": "number", "description": "Total roof area in m²." }, "registeredCompanies": { "type": "integer", "description": "Companies with their registered office in the place." }, "updatedAt": { "type": "string", "format": "date" } }, "description": "One place's building statistics.", "example": { "name": "Iași", "county": "Iași", "buildings": 61234, "addressed": 40211, "built": { "known": 18000, "byEra": [ { "era": "before 1945", "count": 1200 } ], "before1978Share": 0.46 }, "floors": { "known": 30000, "histogram": [ { "floors": "1", "count": 21000 } ], "blocks4plus": 3100 }, "tallest": [ { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "slug": "iasi-palas", "height": 72.0, "label": "Strada Palat 1, Iași" } ], "solar": { "checkedRoofs": 9000, "withPanels": 1450, "imageryYears": [ 2023, 2024 ] }, "roofAreaTotalM2": 5400000, "registeredCompanies": 15400, "updatedAt": "2026-10-01" } }, "PublicStreetList": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "locality", "buildings", "updatedAt" ], "additionalProperties": false, "properties": { "slug": { "type": "string", "description": "For `/public/places/{country}/{slug}/streets/{street}`." }, "name": { "type": "string", "description": "The street's name as its records write it most." }, "locality": { "type": [ "string", "null" ], "description": "The town or village the street is in, where the place holds several." }, "buildings": { "type": "integer", "description": "Buildings on the street with a public page." }, "updatedAt": { "type": "string", "format": "date", "description": "When one of its buildings' facts last changed." } } } } }, "description": "A place's streets where at least 3 buildings have a public page, by name.", "example": { "items": [ { "slug": "milevska", "name": "Milevská", "locality": "Praha", "buildings": 24, "updatedAt": "2026-09-30" } ] } }, "PublicStreet": { "type": "object", "required": [ "slug", "name", "locality", "buildings", "updatedAt", "place", "county", "items" ], "additionalProperties": false, "properties": { "slug": { "type": "string", "description": "For `/public/places/{country}/{slug}/streets/{street}`." }, "name": { "type": "string", "description": "The street's name as its records write it most." }, "locality": { "type": [ "string", "null" ], "description": "The town or village the street is in, where the place holds several." }, "buildings": { "type": "integer", "description": "Buildings on the street with a public page." }, "updatedAt": { "type": "string", "format": "date", "description": "When one of its buildings' facts last changed." }, "place": { "$ref": "#/components/schemas/PublicPlaceReference" }, "county": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicNeighbourBuilding" }, "description": "Every building on the street with a public page, by house number." } }, "description": "One street's page: the street, its place and its buildings.", "example": { "slug": "milevska", "name": "Milevská", "locality": "Praha", "buildings": 24, "updatedAt": "2026-09-30", "place": { "country": "cz", "slug": "praha", "name": "Praha" }, "county": "Hlavní město Praha", "items": [ { "id": "a152dedd-bf51-4bdc-897e-98e1e5e35280", "country": "cz", "slug": "praha-milevska-2094-3", "label": "Milevská 2094/3, Krč, 140 00 Praha 4", "number": "2094/3", "use": "bytový dům", "floors": { "value": 33, "includesUnderground": true }, "built": { "year": 2017, "era": null } } ] } }, "PublicStreetIndex": { "type": "object", "required": [ "items", "nextCursor", "total" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "place", "slug", "updatedAt" ], "additionalProperties": false, "properties": { "place": { "type": "string", "description": "The place's slug." }, "slug": { "type": "string", "description": "The street's slug." }, "updatedAt": { "type": "string", "format": "date" } } } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; null on the last one." }, "total": { "type": "integer", "description": "Street pages in the country." } }, "description": "One page of a country's street pages, larger places and longer streets first.", "example": { "items": [ { "place": "praha", "slug": "milevska", "updatedAt": "2026-09-30" } ], "nextCursor": "10000", "total": 74433 } }, "PublicNeighbourBuilding": { "type": "object", "additionalProperties": false, "required": [ "id", "country", "slug", "label", "number", "use", "floors", "built" ], "description": "Another building with a public page, listed as a link: its own register facts as its page states them.", "properties": { "id": { "type": "string", "format": "uuid" }, "country": { "type": "string", "enum": [ "cz", "dk", "ro" ] }, "slug": { "type": "string", "description": "Not unique: always put the `id` in URLs." }, "label": { "type": "string", "description": "Its one-line address, as on its page." }, "number": { "type": [ "string", "null" ] }, "use": { "type": [ "string", "null" ], "description": "The register's own wording of its use, in the local language; null where unknown." }, "floors": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "value", "includesUnderground" ], "properties": { "value": { "type": "integer" }, "includesUnderground": { "type": "boolean" } } }, { "type": "null" } ] }, "built": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "year", "era" ], "properties": { "year": { "type": [ "integer", "null" ] }, "era": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "distanceM": { "type": "number", "description": "Metres between the two outlines; only in `nearby`." } } }, "PublicSurroundingOutline": { "type": "object", "additionalProperties": false, "required": [ "outline", "id", "slug", "sameStreet" ], "description": "The outline of a building close by, for drawing where the building stands.", "properties": { "outline": { "$ref": "#/components/schemas/PublicPolygon" }, "id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set only where that building has a public page." }, "slug": { "type": [ "string", "null" ] }, "sameStreet": { "type": "boolean", "description": "Its address names the same street in the same locality." } } }, "CountryRequest": { "type": "object", "required": [ "country", "email", "consent" ], "additionalProperties": false, "properties": { "country": { "type": "string", "description": "The country asked for: an ISO 3166-1 alpha-2 code, such as `DE`.", "example": "DE" }, "email": { "type": "string", "format": "email", "description": "Where to write when baseray covers the country. Compared in lower case: the same address asks for a country once.", "example": "ana@example.com" }, "consent": { "type": "boolean", "enum": [ true ], "description": "Must be `true`: the person agrees to be emailed about this country. Kept for 24 months at most and deleted on request (privacy@baseray.ai)." }, "company": { "type": [ "string", "null" ], "description": "The person's company, up to 200 characters." }, "use_case": { "type": [ "string", "null" ], "enum": [ "solar_prospecting", "heating_upgrades", "energy_efficiency", "insurance_underwriting", "real_estate_prospecting", "market_research", "other", null ], "description": "What they want the buildings for." }, "locale": { "type": [ "string", "null" ], "description": "The language to write back in, as a two-letter code (`en`, `ro`, `cs`)." }, "attribution": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Where the person came from before asking (first touch), as the website carries it.", "properties": { "utm_source": { "type": [ "string", "null" ], "description": "Campaign source, up to 200 characters." }, "utm_medium": { "type": [ "string", "null" ], "description": "Campaign medium, up to 200 characters." }, "utm_campaign": { "type": [ "string", "null" ], "description": "Campaign name, up to 200 characters." }, "utm_content": { "type": [ "string", "null" ], "description": "Campaign content, up to 200 characters." }, "utm_term": { "type": [ "string", "null" ], "description": "Campaign term, up to 200 characters." }, "gclid": { "type": [ "string", "null" ], "description": "Google Ads click id, up to 200 characters." }, "referrer_host": { "type": [ "string", "null" ], "description": "Host of the site that sent the person, up to 255 characters." }, "landing_path": { "type": [ "string", "null" ], "description": "The first page the person saw, up to 500 characters." } } } }, "example": { "country": "DE", "email": "ana@example.com", "consent": true, "company": "Example GmbH", "use_case": "insurance_underwriting", "locale": "en" } }, "CountryRequestReceipt": { "type": "object", "required": [ "status", "country" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "received", "live" ], "description": "`received`: the request is on the list (also when this address had asked before). `live`: baseray already covers the country; nothing was stored." }, "country": { "type": "string", "description": "The country asked for, upper case." } }, "example": { "status": "received", "country": "DE" }, "description": "The answer to a country request." }, "RemovalRequest": { "type": "object", "required": [ "country", "registration_number" ], "additionalProperties": false, "properties": { "country": { "type": "string", "enum": [ "RO", "CZ", "DK" ], "description": "The country of the business's register: `RO`, `CZ` or `DK`." }, "registration_number": { "type": "string", "description": "The business's number in its register: a Romanian CUI (2 to 10 digits; a leading `RO` is dropped), a Czech IČO or a Danish CVR number (8 digits each). Spaces, dots and hyphens are ignored.", "example": "12345678" }, "production_unit_numbers": { "type": "array", "items": { "type": "string", "pattern": "^\\d{10}$" }, "maxItems": 100, "description": "Denmark only: the business's production units (P-numbers, 10 digits) to remove with it." }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Where to confirm the removal. Optional; kept only until the request is decided." }, "personal_safety": { "type": "boolean", "description": "True when the person cites a protected address or their safety: the request is then decided within 72 hours." }, "locale": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}$", "description": "The language to confirm in (`en`, `ro`, `cs`, `da`); English otherwise." } } }, "RemovalRequestReceipt": { "type": "object", "required": [ "status", "reference" ], "additionalProperties": false, "description": "Always `received`, whether or not baseray holds the business, so the answer tells nobody what it holds.", "properties": { "status": { "type": "string", "enum": [ "received" ] }, "reference": { "type": "string", "format": "uuid", "description": "Names the request in a later message to privacy@baseray.ai." } } }, "BuildingReportCheckoutRequest": { "type": "object", "required": [ "buildingId", "locale", "returnPath", "consent" ], "additionalProperties": false, "properties": { "buildingId": { "type": "string", "format": "uuid", "description": "The building's baseray id." }, "locale": { "type": "string", "enum": [ "en", "ro", "cs", "da" ], "description": "The building page's language: Checkout's and the delivery email's." }, "returnPath": { "type": "string", "description": "The building's page on baseray.ai in that language, where an abandoned Checkout returns: `/building/`, `/ro/cladire/`, `/cs/budova/` or `/da/bygning/`, then an optional slug and the building's id." }, "consent": { "type": "object", "required": [ "withdrawalWaiver", "terms" ], "additionalProperties": false, "description": "Both must be true.", "properties": { "withdrawalWaiver": { "type": "boolean", "description": "The buyer asks for the report to be delivered at once and acknowledges losing the 14-day right of withdrawal on delivery." }, "terms": { "type": "boolean", "description": "The buyer accepts the terms." } } }, "attribution": { "type": [ "object", "null" ], "additionalProperties": false, "description": "Where the buyer came from before buying (first touch), as a sign-up keeps it.", "properties": { "utmSource": { "type": [ "string", "null" ], "maxLength": 200 }, "utmMedium": { "type": [ "string", "null" ], "maxLength": 200 }, "utmCampaign": { "type": [ "string", "null" ], "maxLength": 200 }, "utmContent": { "type": [ "string", "null" ], "maxLength": 200 }, "utmTerm": { "type": [ "string", "null" ], "maxLength": 200 }, "gclid": { "type": [ "string", "null" ], "maxLength": 200 }, "referrerHost": { "type": [ "string", "null" ], "maxLength": 255 }, "landingPath": { "type": [ "string", "null" ], "maxLength": 500 }, "callToAction": { "type": [ "string", "null" ], "maxLength": 200 } } }, "analyticsAnonymousId": { "type": [ "string", "null" ], "description": "The visit's product analytics anonymous id (letters, digits, dashes, up to 64); dropped in another shape." }, "analyticsSessionId": { "type": [ "string", "null" ], "description": "The visit's product analytics session id (letters, digits, dashes, up to 64); dropped in another shape. With both ids, the report's link carries them (`br_ph`), so its page continues the visit." } }, "description": "A building report bought from its building's page." }, "BuildingReportCheckout": { "type": "object", "required": [ "checkoutUrl" ], "additionalProperties": false, "properties": { "checkoutUrl": { "type": "string", "format": "uri", "description": "The Stripe Checkout page to send the buyer to; it expires after an hour." } }, "example": { "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_a1B2c3" }, "description": "A started report Checkout." }, "BuildingReport": { "type": "object", "required": [ "status", "building", "locale", "paidAt", "accessUntil" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pending", "paid", "expired" ], "description": "`pending` while Checkout is open, `paid`, or `expired` when Checkout closed unpaid." }, "building": { "type": "object", "required": [ "id", "country", "title" ], "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "country": { "type": "string", "description": "Lower case, as the public pages give it (`cz`)." }, "title": { "type": "string", "description": "The building's address as its public page writes it." } } }, "locale": { "type": "string", "enum": [ "en", "ro", "cs", "da" ], "description": "The language it was bought in." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "accessUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Until when the report opens its building: 12 months from payment." } }, "example": { "status": "pending", "building": { "id": "c9eefd1b-8c8d-48fe-8b72-e015374d7720", "country": "cz", "title": "Vinohradská 1200/12, 120 00 Praha 2" }, "locale": "cs", "paidAt": null, "accessUntil": null }, "description": "A bought building report." }, "BuildingReportError": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "consent_required", "not_found", "report_unavailable", "payments_unavailable", "report_not_paid", "report_access_expired", "route_forbidden", "report_analysis_used", "rate_limited", "upstream_unavailable" ] }, "message": { "type": "string" }, "parameter": { "type": "string", "description": "The body field at fault, for `invalid_parameter` and `consent_required`." } }, "example": { "code": "report_not_paid", "message": "This report is not paid." }, "description": "A building report endpoint's refusal." }, "BuildingAddress": { "type": "object", "required": [ "line", "postal_code", "locality", "entrance", "dwellings_at_entrance", "relation" ], "additionalProperties": false, "description": "One address of the building, written once however many records write it: the shown address, a block's entrance, or a corner building's front on another street. Which record gives it is never named.", "properties": { "line": { "type": "string", "description": "The address written the country's way: street and number, then the block (`bl.`) and entrance (`sc.`) where given." }, "postal_code": { "type": [ "string", "null" ], "description": "The address's official postcode where one is known, else the one its record writes; null when none is." }, "locality": { "type": [ "string", "null" ], "description": "The town or village." }, "entrance": { "type": [ "string", "null" ], "description": "The entrance the address names; null for an address that names none." }, "dwellings_at_entrance": { "type": [ "integer", "null" ], "minimum": 0, "description": "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": { "type": [ "string", "null" ], "enum": [ "shown", "same_address", "different_number", "other_street", "another_entrance", null ], "description": "`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." } }, "example": { "line": "Strada Memorandumului 28, bl. A, sc. 1", "postal_code": "400114", "locality": "Cluj-Napoca", "entrance": "1", "dwellings_at_entrance": 24, "relation": "shown" } }, "BuildingAddresses": { "type": "object", "required": [ "confirmation", "addresses" ], "additionalProperties": false, "description": "Every address of the building, the shown one first, and whether its records agree on the shown number.", "properties": { "confirmation": { "type": [ "string", "null" ], "enum": [ "confirmed", "records_disagree", "single_record", null ], "description": "`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": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingAddress" }, "description": "Every address, the shown one first." } }, "example": { "confirmation": "confirmed", "addresses": [ { "line": "Strada Memorandumului 28, bl. A, sc. 1", "postal_code": "400114", "locality": "Cluj-Napoca", "entrance": "1", "dwellings_at_entrance": 24, "relation": "shown" } ] } }, "FloorUnits": { "type": "object", "required": [ "floor_kind", "floor_number", "units", "dwellings" ], "additionalProperties": false, "description": "The units the building's record lists on one floor.", "properties": { "floor_kind": { "type": "string", "enum": [ "basement", "semi_basement", "ground", "upper", "attic" ], "description": "Which kind of floor: `basement`, `semi_basement`, `ground`, `upper` or `attic`." }, "floor_number": { "type": [ "integer", "null" ], "description": "Basements and upper floors only, counted from 1; null for the others." }, "units": { "type": "integer", "minimum": 0, "description": "The listed units of every kind on the floor." }, "dwellings": { "type": "integer", "minimum": 0, "description": "The listed dwellings among them." } }, "example": { "floor_kind": "upper", "floor_number": 4, "units": 23, "dwellings": 23 } }, "UnitKindCount": { "type": "object", "required": [ "kind", "units" ], "additionalProperties": false, "description": "How many of the units the building's record lists are of one kind.", "properties": { "kind": { "type": "string", "enum": [ "dwelling", "commercial", "parking", "storage", "other" ], "description": "`dwelling`, `commercial` (a shop, an office or other business premises), `parking`, `storage` or `other`; a unit the record gives no kind is `other`." }, "units": { "type": "integer", "minimum": 1, "description": "The listed units of that kind." } }, "example": { "kind": "parking", "units": 94 } }, "EntranceDwellings": { "type": "object", "required": [ "entrance", "dwellings" ], "additionalProperties": false, "description": "The dwellings the building's record counts behind one of its entrances.", "properties": { "entrance": { "type": "string", "description": "The entrance, by its address as the record writes it." }, "dwellings": { "type": "integer", "minimum": 0, "description": "The dwellings counted behind it." } }, "example": { "entrance": "Strada Memorandumului 28, sc. 1", "dwellings": 24 } }, "UnitsSummary": { "type": "object", "required": [ "listed", "listed_dwellings", "stated", "stated_dwellings", "list_is_complete", "by_floor", "by_kind", "entrances", "entrance_dwellings" ], "additionalProperties": false, "description": "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`.", "properties": { "listed": { "type": [ "integer", "null" ], "minimum": 1, "description": "The units the record lists; null when it lists none, which says nothing of how many there are." }, "listed_dwellings": { "type": [ "integer", "null" ], "minimum": 0, "description": "The dwellings among the listed units; null when none are listed." }, "stated": { "type": [ "integer", "null" ], "minimum": 0, "description": "The units the record states the building has; null when it states no total." }, "stated_dwellings": { "type": [ "integer", "null" ], "minimum": 0, "description": "The dwellings the record states the building has; null when it states no total." }, "list_is_complete": { "type": "boolean", "description": "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": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/FloorUnits" }, "description": "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." }, "by_kind": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/UnitKindCount" }, "description": "The listed units of each kind, kinds the list holds none of left out. Null when no units are listed." }, "entrances": { "type": "array", "items": { "type": "string" }, "description": "The entrances the listed units are reached by, as the record names them, in reading order." }, "entrance_dwellings": { "type": "array", "items": { "$ref": "#/components/schemas/EntranceDwellings" }, "description": "The dwellings the record counts behind each entrance; empty when it counts none." } }, "example": { "listed": 118, "listed_dwellings": 96, "stated": 118, "stated_dwellings": 96, "list_is_complete": true, "by_floor": [ { "floor_kind": "ground", "floor_number": null, "units": 22, "dwellings": 0 }, { "floor_kind": "upper", "floor_number": 1, "units": 24, "dwellings": 24 } ], "by_kind": [ { "kind": "dwelling", "units": 96 }, { "kind": "commercial", "units": 4 }, { "kind": "storage", "units": 18 } ], "entrances": [ "A", "B" ], "entrance_dwellings": [] } }, "BuildingUnit": { "type": "object", "required": [ "designation", "floor", "floor_kind", "floor_number", "entrance", "kind", "use", "area_m2", "rooms", "cadastral_number" ], "additionalProperties": false, "description": "One unit the building's record lists, as the record words it.", "properties": { "designation": { "type": [ "string", "null" ], "description": "The unit's number, name or door as the record writes it, e.g. `275`, `Parcare 12`." }, "floor": { "type": [ "string", "null" ], "description": "The floor as the record words it, e.g. `P`, `ETAJ 7`; null when the record names none for the unit." }, "floor_kind": { "type": [ "string", "null" ], "enum": [ "basement", "semi_basement", "ground", "upper", "attic", null ], "description": "Which kind of floor it is on; null when not known." }, "floor_number": { "type": [ "integer", "null" ], "description": "Basements and upper floors only, counted from 1." }, "entrance": { "type": [ "string", "null" ], "description": "The entrance the unit is reached by, as the record names it." }, "kind": { "type": [ "string", "null" ], "enum": [ "dwelling", "commercial", "parking", "storage", "other", null ], "description": "`dwelling`, `commercial`, `parking`, `storage` or `other`; null when the record gives none." }, "use": { "type": [ "string", "null" ], "description": "The use the record states for the unit, in its wording." }, "area_m2": { "type": [ "number", "null" ], "minimum": 0, "description": "The unit's area as the record states it." }, "rooms": { "type": [ "integer", "null" ], "minimum": 0, "description": "The rooms the record states." }, "cadastral_number": { "type": [ "string", "null" ], "description": "The unit's own cadastral number, where the record keeps one." } }, "example": { "designation": "275", "floor": "ETAJ 7", "floor_kind": "upper", "floor_number": 7, "entrance": "B", "kind": "dwelling", "use": "locuinta", "area_m2": 54.2, "rooms": 2, "cadastral_number": null } }, "BuildingUnitPageMeta": { "type": "object", "required": [ "listed", "stated", "list_is_complete", "matched", "limit", "offset" ], "additionalProperties": false, "description": "How the page stands against the building's whole list of units.", "properties": { "listed": { "type": "integer", "minimum": 0, "description": "The units the record lists; 0 when it lists none, which says nothing of how many there are." }, "stated": { "type": [ "integer", "null" ], "minimum": 0, "description": "The units the record states the building has; null when it states no total." }, "list_is_complete": { "type": "boolean", "description": "True when the record lists units and its list matches every total it states." }, "matched": { "type": "integer", "minimum": 0, "description": "The listed units the answer is about: every one, or those `unit` finds." }, "limit": { "type": "integer", "minimum": 1, "description": "The page size asked for." }, "offset": { "type": "integer", "minimum": 0, "description": "The matched units skipped." } }, "example": { "listed": 736, "stated": 736, "list_is_complete": true, "matched": 1, "limit": 200, "offset": 0 } }, "BuildingUnitPage": { "type": "object", "required": [ "data", "meta", "links" ], "additionalProperties": false, "description": "One page of the units a building's record lists.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingUnit" }, "description": "The page of matched units, by number, then by name." }, "meta": { "$ref": "#/components/schemas/BuildingUnitPageMeta" }, "links": { "$ref": "#/components/schemas/Links" } }, "example": { "data": [ { "designation": "275", "floor": "ETAJ 7", "floor_kind": "upper", "floor_number": 7, "entrance": "B", "kind": "dwelling", "use": "locuinta", "area_m2": 54.2, "rooms": 2, "cadastral_number": null } ], "meta": { "listed": 736, "stated": 736, "list_is_complete": true, "matched": 1, "limit": 200, "offset": 0 }, "links": { "next": null } } }, "RecordSheetRow": { "type": "object", "required": [ "label", "value", "unit" ], "additionalProperties": false, "description": "One fact of the building's record, as the record words it.", "properties": { "label": { "type": "string", "description": "The fact's name, or a list entry's own wording." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value as the record states it: a wording, a number in `unit`, or a yes or no." }, "unit": { "type": [ "string", "null" ], "description": "The unit of a quantity as written, e.g. `m2`, `W/m2K`, `kWh/m2/year`; null for wordings and counts." } }, "example": { "label": "Heated floor area", "value": 2410.5, "unit": "m2" } }, "RecordSheetSection": { "type": "object", "required": [ "title", "rows" ], "additionalProperties": false, "description": "One section of the building's record, as its register lays it out.", "properties": { "title": { "type": "string", "description": "The section's title." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/RecordSheetRow" }, "description": "The facts in the section." } }, "example": { "title": "Performance", "rows": [ { "label": "Heated floor area", "value": 2410.5, "unit": "m2" } ] } }, "RecordSheet": { "type": "object", "required": [ "exists", "validated", "cadastral_number", "property_number", "land_book_number", "read_on", "sections" ], "additionalProperties": false, "description": "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.", "properties": { "exists": { "type": [ "boolean", "null" ], "description": "False when the record says the building no longer stands; null where the register keeps no such mark." }, "validated": { "type": [ "boolean", "null" ], "description": "Whether the register marks the record checked; null where it keeps no such mark." }, "cadastral_number": { "type": [ "string", "null" ], "description": "The building's cadastral number, where the record keeps one." }, "property_number": { "type": [ "string", "null" ], "description": "The property number, where the record keeps one." }, "land_book_number": { "type": [ "string", "null" ], "description": "The land book number, where the record keeps one." }, "read_on": { "type": [ "string", "null" ], "format": "date", "description": "The day the record was last read." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/RecordSheetSection" }, "description": "Every fact on record, by section; empty when the record states none beyond its numbers." } }, "example": { "exists": true, "validated": true, "cadastral_number": "262812-C1", "property_number": null, "land_book_number": "262812", "read_on": "2026-10-06", "sections": [ { "title": "Performance", "rows": [ { "label": "Heated floor area", "value": 2410.5, "unit": "m2" } ] } ] } }, "RoofPlane": { "type": "object", "required": [ "plane", "facing", "azimuth_degrees", "pitch_degrees", "area_m2", "sunshine_hours_per_year", "panels" ], "additionalProperties": false, "description": "One plane of the analysed roof.", "properties": { "plane": { "type": "integer", "minimum": 1, "description": "The number the analysis gives the plane." }, "facing": { "type": "string", "enum": [ "north", "north-east", "east", "south-east", "south", "south-west", "west", "north-west" ], "description": "The compass direction the plane faces." }, "azimuth_degrees": { "type": "number", "description": "The bearing the plane faces: 0 north, 90 east, 180 south." }, "pitch_degrees": { "type": "number", "description": "The plane's slope from the horizontal." }, "area_m2": { "type": "number", "minimum": 0, "description": "The plane's area." }, "sunshine_hours_per_year": { "type": [ "number", "null" ], "minimum": 0, "description": "The sunshine the plane gets in a year; null when not analysed." }, "panels": { "type": "integer", "minimum": 0, "description": "Panels the largest layout puts on the plane." } }, "example": { "plane": 1, "facing": "south", "azimuth_degrees": 181.4, "pitch_degrees": 32.0, "area_m2": 64.3, "sunshine_hours_per_year": 1412.0, "panels": 28 } }, "RoofAnalysis": { "type": "object", "required": [ "whole_roof_area_m2", "ground_area_m2", "peak_sunshine_hours_per_year", "yearly_irradiance_kwh_per_m2", "imagery_date", "imagery_quality", "confidence", "planes_are_assumed", "roof_survey", "panel_capacity_w", "panel_width_m", "panel_height_m", "planes" ], "additionalProperties": false, "description": "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.", "properties": { "whole_roof_area_m2": { "type": [ "number", "null" ], "minimum": 0, "description": "The whole roof's area." }, "ground_area_m2": { "type": [ "number", "null" ], "minimum": 0, "description": "The ground the analysed roof covers." }, "peak_sunshine_hours_per_year": { "type": [ "number", "null" ], "minimum": 0, "description": "Peak sunshine hours a year at the roof." }, "yearly_irradiance_kwh_per_m2": { "type": [ "number", "null" ], "minimum": 0, "description": "The solar energy a square metre of the roof receives in a year." }, "imagery_date": { "type": [ "string", "null" ], "format": "date", "description": "The date of the imagery the roof was read from; null when undated or assumed." }, "imagery_quality": { "type": [ "string", "null" ], "description": "The imagery's quality as the analysis grades it." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "The analysis's confidence, 0 to 1." }, "planes_are_assumed": { "type": [ "boolean", "null" ], "description": "True where the planes are an estimate's assumption, false where they were measured, null where unsaid." }, "roof_survey": { "type": [ "string", "null" ], "enum": [ "lidar", "image_matching", null ], "description": "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": { "type": [ "number", "null" ], "minimum": 0, "description": "The power of the panel the layout assumes." }, "panel_width_m": { "type": [ "number", "null" ], "minimum": 0, "description": "The width of that panel." }, "panel_height_m": { "type": [ "number", "null" ], "minimum": 0, "description": "The height of that panel." }, "planes": { "type": "array", "items": { "$ref": "#/components/schemas/RoofPlane" }, "description": "Every plane of the roof, by its number." } }, "example": { "whole_roof_area_m2": 182.4, "ground_area_m2": 151.0, "peak_sunshine_hours_per_year": 1390.0, "yearly_irradiance_kwh_per_m2": 1310.0, "imagery_date": "2023-06-14", "imagery_quality": "HIGH", "confidence": 0.92, "planes_are_assumed": false, "roof_survey": null, "panel_capacity_w": 400.0, "panel_width_m": 1.045, "panel_height_m": 1.879, "planes": [ { "plane": 1, "facing": "south", "azimuth_degrees": 181.4, "pitch_degrees": 32.0, "area_m2": 64.3, "sunshine_hours_per_year": 1412.0, "panels": 28 } ] } }, "ClimatePeriod": { "type": "object", "required": [ "period", "from", "to", "data_through", "coldest_day_c", "hottest_day_c", "frost_days", "hot_days", "precipitation_mm", "wet_days", "wettest_day_mm" ], "additionalProperties": false, "description": "The local climate at the building over one period.", "properties": { "period": { "type": "string", "enum": [ "latest_year", "recent_average", "current_year" ], "description": "`latest_year` (the last complete year), `recent_average` (yearly average over the recent years) or `current_year` (this year so far, preliminary)." }, "from": { "type": [ "string", "null" ], "description": "Where the period starts: a year, or a date for `current_year`." }, "to": { "type": [ "string", "null" ], "description": "Where the period ends: a year, or a date for `current_year`." }, "data_through": { "type": [ "string", "null" ], "format": "date", "description": "The last day the data covers." }, "coldest_day_c": { "type": [ "number", "null" ], "description": "The lowest daily temperature, °C." }, "hottest_day_c": { "type": [ "number", "null" ], "description": "The highest daily temperature, °C." }, "frost_days": { "type": [ "number", "null" ], "minimum": 0, "description": "Days below freezing." }, "hot_days": { "type": [ "number", "null" ], "minimum": 0, "description": "Hot days." }, "precipitation_mm": { "type": [ "number", "null" ], "minimum": 0, "description": "Rainfall over the year, mm." }, "wet_days": { "type": [ "number", "null" ], "minimum": 0, "description": "Wet days." }, "wettest_day_mm": { "type": [ "number", "null" ], "minimum": 0, "description": "Rainfall on the wettest day, mm." } }, "example": { "period": "recent_average", "from": "2016", "to": "2025", "data_through": "2025-12-31", "coldest_day_c": -14.2, "hottest_day_c": 36.8, "frost_days": 92.4, "hot_days": 31.5, "precipitation_mm": 612.3, "wet_days": 104.2, "wettest_day_mm": 48.6 } }, "HeatingDegreeDays": { "type": "object", "required": [ "period", "from", "to", "degree_days" ], "additionalProperties": false, "description": "The heating degree-days of the building's location over one period.", "properties": { "period": { "type": "string", "enum": [ "standard_normal", "recent_average", "latest_year" ], "description": "`standard_normal` (the climate normal), `recent_average` (yearly average over the recent years) or `latest_year` (the last complete year)." }, "from": { "type": "string", "description": "The first year of the period." }, "to": { "type": "string", "description": "The last year of the period." }, "degree_days": { "type": "number", "minimum": 0, "description": "Heating degree-days, K·d." } }, "example": { "period": "standard_normal", "from": "1991", "to": "2020", "degree_days": 3202.0 } }, "Climate": { "type": "object", "required": [ "periods", "heating_degree_days", "temperature_trend_c_per_decade" ], "additionalProperties": false, "description": "The local climate at the building, from gridded climate data for its location, never an on-site measurement.", "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/ClimatePeriod" }, "description": "The temperatures, frost and hot days and rainfall per period; a period with no figure on record is left out." }, "heating_degree_days": { "type": "array", "items": { "$ref": "#/components/schemas/HeatingDegreeDays" }, "description": "The heating degree-days per period, the climate normal first; a period not on record is left out." }, "temperature_trend_c_per_decade": { "type": [ "number", "null" ], "description": "How fast the location has warmed, °C per decade; null where the trend is not on record or has no clear direction." } }, "example": { "periods": [ { "period": "recent_average", "from": "2016", "to": "2025", "data_through": "2025-12-31", "coldest_day_c": -14.2, "hottest_day_c": 36.8, "frost_days": 92.4, "hot_days": 31.5, "precipitation_mm": 612.3, "wet_days": 104.2, "wettest_day_mm": 48.6 } ], "heating_degree_days": [ { "period": "standard_normal", "from": "1991", "to": "2020", "degree_days": 3202.0 } ], "temperature_trend_c_per_decade": 0.48 } }, "EnergyNetworkLevel": { "type": "object", "required": [ "network", "level", "present", "year" ], "additionalProperties": false, "description": "Whether a gas or district-heating network is on record at one level, from the locality down to the building.", "properties": { "network": { "type": "string", "enum": [ "natural_gas", "district_heating" ], "description": "The network." }, "level": { "type": "string", "enum": [ "locality", "service_area", "street", "address", "building" ], "description": "How close to the building the evidence reaches: the locality, the service area, the street, the address or the building's own connection." }, "present": { "type": "boolean", "description": "Whether the network is on record at that level." }, "year": { "type": [ "integer", "null" ], "description": "The year the evidence refers to." } }, "example": { "network": "natural_gas", "level": "street", "present": true, "year": 2024 } }, "HeatingEraScenario": { "type": "object", "required": [ "first_year", "last_year", "useful_heat_kwh_per_year", "is_taken" ], "additionalProperties": false, "description": "The heat the building would need for space heating had it been built in one construction period.", "properties": { "first_year": { "type": [ "integer", "null" ], "description": "The period's first year; null for the earliest." }, "last_year": { "type": [ "integer", "null" ], "description": "The period's last year; null for the latest." }, "useful_heat_kwh_per_year": { "type": "number", "minimum": 0, "description": "The heat need under that period." }, "is_taken": { "type": "boolean", "description": "Whether the other figures assume this period." } }, "example": { "first_year": 1961, "last_year": 1980, "useful_heat_kwh_per_year": 182000.0, "is_taken": true } }, "HeatPumpScenario": { "type": "object", "required": [ "seasonal_performance_factor", "electricity_kwh_per_year" ], "additionalProperties": false, "description": "The electricity a heat pump would use for the building's space heating at one seasonal performance factor.", "properties": { "seasonal_performance_factor": { "type": "number", "minimum": 0, "description": "The seasonal performance factor assumed." }, "electricity_kwh_per_year": { "type": [ "number", "null" ], "minimum": 0, "description": "The electricity a year." } }, "example": { "seasonal_performance_factor": 3.0, "electricity_kwh_per_year": 60667.0 } }, "HeatingEstimate": { "type": "object", "required": [ "useful_heat_kwh_per_year", "useful_heat_low_kwh_per_year", "useful_heat_high_kwh_per_year", "useful_heat_kwh_per_m2_per_year", "heated_floor_area_m2", "heated_floor_area_basis", "useful_heat_kwh_per_dwelling_per_year", "dwelling_count", "delivered_energy_kwh_per_year", "expected_energy_kwh_per_year", "peak_heat_load_kw", "peak_heat_load_basis", "design_outdoor_temperature_c", "hot_water_heat_kwh_per_year", "hot_water_persons", "hot_water_occupancy_basis", "construction_period_is_on_record", "era_scenarios", "neighbours_are_measured", "neighbour_wall_share", "heat_pump_scenarios" ], "additionalProperties": false, "description": "The building's heating estimate. Every figure is a model estimate, never a metered value, an energy certificate or a sizing.", "properties": { "useful_heat_kwh_per_year": { "type": [ "number", "null" ], "description": "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": { "type": [ "number", "null" ], "description": "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": { "type": [ "number", "null" ], "description": "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": { "type": [ "number", "null" ], "description": "The heat need per m² of heated floor area." }, "heated_floor_area_m2": { "type": [ "number", "null" ], "description": "The heated floor area the need is worked out on." }, "heated_floor_area_basis": { "type": [ "string", "null" ], "description": "What the heated floor area rests on, e.g. `register_heated_area` or `volume_share`." }, "useful_heat_kwh_per_dwelling_per_year": { "type": [ "number", "null" ], "description": "The heat need of one dwelling on average, where the dwellings are counted." }, "dwelling_count": { "type": [ "integer", "null" ], "description": "The dwellings that figure is per." }, "delivered_energy_kwh_per_year": { "type": [ "number", "null" ], "description": "The energy delivered to the heating system for that need." }, "expected_energy_kwh_per_year": { "type": [ "number", "null" ], "description": "The energy the building is expected to use for heating." }, "peak_heat_load_kw": { "type": [ "number", "null" ], "description": "The peak heat load." }, "peak_heat_load_basis": { "type": [ "string", "null" ], "description": "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": { "type": [ "number", "null" ], "description": "The outdoor temperature the peak heat load is worked out at, °C." }, "hot_water_heat_kwh_per_year": { "type": [ "number", "null" ], "description": "The heat in the hot water, apart from space heating and in none of the other figures." }, "hot_water_persons": { "type": [ "number", "null" ], "description": "The people the hot water is worked out for." }, "hot_water_occupancy_basis": { "type": [ "string", "null" ], "description": "Where those people come from: `counted_dwellings`, `one_household` or `heated_floor_area`." }, "construction_period_is_on_record": { "type": [ "boolean", "null" ], "description": "False when the construction period behind the estimate is assumed, not read from the building's own record." }, "era_scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/HeatingEraScenario" }, "description": "Where the construction year is not on record: the need under each construction period." }, "neighbours_are_measured": { "type": [ "boolean", "null" ], "description": "False when the neighbouring buildings were not measured and every wall was taken to face the weather." }, "neighbour_wall_share": { "type": [ "number", "null" ], "description": "The share of the walls, 0 to 1, standing against neighbouring buildings; null where they were not measured." }, "heat_pump_scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/HeatPumpScenario" }, "description": "The electricity a heat pump would use per seasonal performance factor." } }, "example": { "useful_heat_kwh_per_year": 182000.0, "useful_heat_low_kwh_per_year": null, "useful_heat_high_kwh_per_year": null, "useful_heat_kwh_per_m2_per_year": 75.5, "heated_floor_area_m2": 2410.5, "heated_floor_area_basis": "register_heated_area", "useful_heat_kwh_per_dwelling_per_year": 7583.0, "dwelling_count": 24, "delivered_energy_kwh_per_year": 214000.0, "expected_energy_kwh_per_year": 196000.0, "peak_heat_load_kw": 96.4, "peak_heat_load_basis": "screening_estimate", "design_outdoor_temperature_c": -15.0, "hot_water_heat_kwh_per_year": 41000.0, "hot_water_persons": 52.8, "hot_water_occupancy_basis": "counted_dwellings", "construction_period_is_on_record": true, "era_scenarios": [], "neighbours_are_measured": true, "neighbour_wall_share": 0.18, "heat_pump_scenarios": [ { "seasonal_performance_factor": 3.0, "electricity_kwh_per_year": 60667.0 } ] } } } } }