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
                                                    # hour axis is UTC; pass
                                                    # timezone="Europe/Paris"
                                                    # for local standard time

You can also configure from the command line:

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

What it provides

The MIT LICENSE covers the code only. Each dataset keeps its upstream licence, and every derived blob inherits the licence of the source it came from — there is no separate "buildingdata data licence". Two rows are not Licence Ouverte, and both matter for a publication: ELMAS is CC BY 4.0 (cite the paper), and ERA5 is CC BY 4.0 behind a personal Copernicus account, so an ERA5-dependent workflow is not anonymously reproducible. The occupant diaries and the activity library derive from the INSEE Enquête Emploi du temps 2009-2010, which is obtained on request and is not redistributed here. The Datasets documentation page carries the per-dataset attribution string to reproduce, the exact upstream vintage, and the verification date.

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). The documentation page Datasets describes each dataset in detail — provenance, schema, units — and how buildingmodel / building_eload consume it.

Bulk prefetch for large-scale simulations

The live APIs fetch one IRIS or one grid point at a time. For campaigns over thousands of IRIS, prefetch whole years and départements into the local cache once, then read them lock-free from any number of parallel workers:

buildingdata configure --cds-key YOUR-CDS-KEY   # ERA5 needs Copernicus CDS credentials
buildingdata prefetch era5   --years 2019       # ~1.5 GB/year; one Zarr store over metropolitan France
buildingdata prefetch bdtopo --departments 75 92  # IGN 7z -> per-département GeoParquet
buildingdata cache info                          # sizes + completed bulk partitions

import buildingdata as bd

# After the prefetch, the same functions read the bulk cache automatically:
buildings = bd.get_bdtopo("751010101")                 # source="auto" by default
frame     = bd.get_era5_frame(48.85, 2.35, year=2019)  # EPW-format DataFrame, no EPW file

# Many IRIS at once — one partition scan + spatial join per département
frames = bd.get_bdtopo_bulk(["751010101", "751010102", "920020101"])

# Or force the local cache (fails fast instead of hitting the network):
buildings = bd.get_bdtopo("751010101", source="bulk")

BDTOPO bulk prefetch needs the bulk extra (pip install "buildingdata[bulk]"), ERA5 the era5 extra. See the documentation page Bulk prefetch for large-scale simulations for source selection ("auto"/"bulk"/"wfs"/"cds"), disk sizes, concurrency guarantees and BDTOPO vintage notes.

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[bulk]"   # BDTOPO bulk prefetch (py7zr)
pip install "buildingdata[timezone]"  # ERA5 timezone="local_standard" (timezonefinder)
pip install "buildingdata[docs]"   # build the Sphinx documentation

Requires Python ≥ 3.10.

License

Released under the MIT License.