API reference · v1.0.0

baseray API

The same building records you see in the app, as JSON: buildings in an area ranked by size, one building’s full record, the businesses registered at its address, and the buildings at a point.

Coverage grows country by country: Romania and Czechia today. An area outside the covered countries answers with no buildings, not an error. See the live countries and request yours.

Working in ChatGPT, Claude or Cursor? Connect the baseray MCP server instead: no code, no key.

Base URL

https://api.baseray.ai/v1

Responses are JSON with snake_case fields, metric units and ISO 8601 dates. Unknown values are null; estimates say so in a basis field.

Your first request

curl "https://api.baseray.ai/v1/buildings?bbox=25.55,45.60,25.68,45.70&sort=volume&limit=25&offset=0&category=residential_house&building_type=&roof_shape=gabled&address_corroboration=corroborated&measured_height_only=false&solar_presence=registered&exclude_solar_presence=registered&existing_solar_panels=detected&has_solar_potential=false&has_3d_model=false&has_registered_business=false&registered_business_turnover_currency=RON&has_annual_heating_estimate=false&has_thermal_assessment=false&has_peak_heat_load=false&has_recent_climate_trend=false&has_recent_temperature_extremes=false&has_recent_precipitation=false&flood_zone=5_year&seismic_risk_class=RsI" \
  -H "Authorization: Bearer $BASERAY_API_KEY"

const response = await fetch("https://api.baseray.ai/v1/buildings?bbox=25.55,45.60,25.68,45.70&sort=volume&limit=25&offset=0&category=residential_house&building_type=&roof_shape=gabled&address_corroboration=corroborated&measured_height_only=false&solar_presence=registered&exclude_solar_presence=registered&existing_solar_panels=detected&has_solar_potential=false&has_3d_model=false&has_registered_business=false&registered_business_turnover_currency=RON&has_annual_heating_estimate=false&has_thermal_assessment=false&has_peak_heat_load=false&has_recent_climate_trend=false&has_recent_temperature_extremes=false&has_recent_precipitation=false&flood_zone=5_year&seismic_risk_class=RsI", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BASERAY_API_KEY}` },
});
const result = await response.json();

import os
import requests

response = requests.get(
    "https://api.baseray.ai/v1/buildings",
    params={"bbox": "25.55,45.60,25.68,45.70", "sort": "volume", "limit": "25", "offset": "0", "category": "residential_house", "building_type": "", "roof_shape": "gabled", "address_corroboration": "corroborated", "measured_height_only": "false", "solar_presence": "registered", "exclude_solar_presence": "registered", "existing_solar_panels": "detected", "has_solar_potential": "false", "has_3d_model": "false", "has_registered_business": "false", "registered_business_turnover_currency": "RON", "has_annual_heating_estimate": "false", "has_thermal_assessment": "false", "has_peak_heat_load": "false", "has_recent_climate_trend": "false", "has_recent_temperature_extremes": "false", "has_recent_precipitation": "false", "flood_zone": "5_year", "seismic_risk_class": "RsI"},
    headers={"Authorization": f"Bearer {os.environ['BASERAY_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
result = response.json()

Authentication

Every request needs a workspace API key. Create one in the app under Settings → API keys; the key is shown once, so store it in your secret manager.

Send the key in the Authorization header as a bearer token. Keys belong to the workspace: anyone in the workspace can create one, and the creator or a workspace owner can revoke it. A key stops working when it is revoked, when it expires, or when its creator leaves the workspace.

Authorization: Bearer br_live_…

Rate limits and quotas

Each key can make 60 requests a minute. Each workspace can make 5,000 requests a day, counted per UTC day across all its keys.

Every response tells you where you stand: RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the minute, X-Daily-Quota-Limit and X-Daily-Quota-Remaining for the day. Over a limit you get 429 with a Retry-After header; wait that many seconds before retrying.

Credits

Every building an answer returns costs the workspace 1 credit, once: a building the workspace opened in the last 365 days, in the app, the API or an AI assistant, is free. A page of results is charged all or nothing; when the workspace has too few credits left, the request answers 402 with insufficient_credits and returns nothing.

X-Credits-Charged and X-Credits-Remaining say what a request cost and what is left. A new account comes with 5 credits, so it opens 5 buildings free with no card; they last 30 days from sign-up. After that, credits come with a plan: the pricing page lists them.

Errors

Errors use the HTTP status and one JSON shape, so you can branch on error.code:

{
  "error": {
    "code": "invalid_parameter",
    "message": "bbox must be minLon,minLat,maxLon,maxLat.",
    "parameter": "bbox"
  }
}

Status	Code	Meaning
400	invalid_parameter	A parameter is missing or invalid. `error.parameter` names it.
401	missing_api_key	No `Authorization: Bearer` header was sent.
401	invalid_api_key	The key does not exist.
401	revoked_api_key	The key was revoked.
401	expired_api_key	The key has expired. Create a new one.
402	insufficient_credits	The workspace has fewer credits left than the buildings in the answer it has not opened. Nothing was returned or charged.
403	insufficient_scope	The key may not call this endpoint.
403	workspace_access_revoked	The key’s creator no longer belongs to the workspace.
404	not_found	No building has this id.
429	rate_limited	Over 60 requests this minute for this key. Retry after `Retry-After` seconds.
429	quota_exceeded	The workspace used its daily requests. The quota resets at midnight UTC.
503	upstream_unavailable	The data service is temporarily unavailable. Retry with exponential backoff.

Pagination

List endpoints take limit and offset and return meta.total with links.next, the URL of the next page or null on the last one. offset + limit may not exceed 10,000.

Counting stops at 10,000 buildings. When meta.total_is_capped is true, the area holds more than that: narrow the box or add filters rather than paging further.

Endpoints

Buildings

Search, look up and read buildings.

Registered businesses

Businesses whose registered office is a building's address. A registered office is never ownership or occupancy.

GET /buildings/{building_id}/registered-businesses Businesses registered at a building's address

Public building pages

The facts behind baseray's public building and place pages. No API key; limited per client address; cacheable.

Countries

Ask for baseray in a country it does not cover yet. No API key; limited per visitor.

POST /public/country-requests Request a country

Removal requests

Ask for a business to be removed from baseray. No API key; limited per visitor.

POST /public/removal-requests Ask for a business to be removed

Building reports

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.