buildingdata 0.1.1

Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather

buildingdata

Data-management layer for buildingmodel. buildingdata delivers clean, ready-to-use building, demographic and weather datasets for French building energy inference, and caches everything locally so repeated calls don't re-download.

pip install buildingdata

Quick start

import buildingdata as bd

# One-time configuration (bucket, cache dir, credentials).
# The public bucket works anonymously, so this is optional.
bd.configure()

# Reference datasets (downloaded once from Google Cloud Storage, then cached)
census    = bd.get_census()        # INSEE census            -> polars DataFrame
districts = bd.get_districts()     # IRIS district geometry  -> geopandas GeoDataFrame
diagnosis = bd.get_diagnosis()     # ADEME energy diagnoses  -> polars DataFrame
gas       = bd.get_gas_network()   # GRDF gas network routes -> geopandas GeoDataFrame

# On-demand datasets (fetched live from public APIs)
buildings = bd.get_bdtopo("751010101")           # per-IRIS building geometry (IGN WFS)
epw       = bd.get_era5_climate(48.85, 2.35, 2020)  # ERA5 weather -> synthetic EPW

You can also configure from the command line:

buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata

What it provides

Function	Source	Returns
get_census()	INSEE census (GCS)	polars DataFrame
get_districts()	IRIS geometries (GCS)	geopandas GeoDataFrame
get_diagnosis()	ADEME energy performance diagnoses (GCS)	polars DataFrame
get_gas_network()	GRDF gas network routes (GCS)	geopandas GeoDataFrame
get_bdtopo(iris_code)	IGN Géoplateforme WFS (live)	geopandas GeoDataFrame
get_era5_climate(lat, lon, year)	Copernicus CDS (live)	path to EPW file

Reference datasets are pulled from a public Google Cloud Storage bucket and cached locally with generation-based freshness checks. French geospatial data uses CRS EPSG:2154 (Lambert-93).

Configuration

Settings are resolved from (in order) explicit arguments, environment variables, and ~/.config/buildingdata/config.ini:

• bucket — GCS bucket holding the reference datasets
• cache directory — where downloaded data is stored locally
• credentials — path to a GCS service-account JSON (omit for anonymous access to the public bucket)

Installation extras

pip install "buildingdata[era5]"   # ERA5 weather (cdsapi, xarray, pvlib, ...)
pip install "buildingdata[docs]"   # build the Sphinx documentation

Requires Python ≥ 3.10.

License

Released under the MIT License.