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

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 in the following precedence order:

1. Explicit function arguments / CLI options
2. Environment variables (BUILDINGDATA_BUCKET, BUILDINGDATA_CACHE_DIR, GOOGLE_APPLICATION_CREDENTIALS)
3. Global configuration file (~/.config/buildingdata/config.ini)
4. Dynamic defaults

Configurable settings:

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

Cache Behavior & Multi-Project Sharing

• Default (Unconfigured): The cache directory is namespaced per installation (~/.local/share/buildingdata/cache/<install-id> on Linux/macOS). Each virtualenv or package installation receives its own unique cache subfolder to prevent collisions between environments.
• Sharing Across Projects: To share a single cache directory across multiple repositories, virtualenvs, or Snakemake pipelines, set the BUILDINGDATA_CACHE_DIR environment variable or write a global configuration file:

# Via CLI (writes ~/.config/buildingdata/config.ini):
buildingdata configure --cache-dir /path/to/shared/cache

# Or via environment variable:
export BUILDINGDATA_CACHE_DIR="/path/to/shared/cache"

Because ~/.config/buildingdata/config.ini is stored in your home directory, configuring it once applies globally to all projects and virtual environments for your user account.

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.