Skip to main content

buildingdata

PyPI Python

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

Function Source Licence Returns Consumed by
get_census() INSEE census (GCS) Licence Ouverte 2.0 polars DataFrame buildingmodel — dwelling inference
get_census_individuals() INSEE census individuals, activitymodel vocabulary (GCS) Licence Ouverte 2.0 polars DataFrame buildingmodel — occupant inference
get_districts() IRIS geometries (GCS) Licence Ouverte 2.0 geopandas GeoDataFrame buildingmodel — geocoding; building_eload — district lookup
get_diagnosis() ADEME energy performance diagnoses (GCS) Licence Ouverte 2.0 polars DataFrame buildingmodel — envelope & system inference
get_gas_network() GRDF gas network routes (GCS) Licence Ouverte (Etalab) geopandas GeoDataFrame buildingmodel — gas-connection inference
get_ore() Agence ORE annual consumption per IRIS (GCS) Licence Ouverte 2.0 polars DataFrame building_eload — calibration target
get_enedis_national() / get_enedis_regional() Enedis conso-inf36 measured consumption (GCS) Licence Ouverte 2.0 polars DataFrame building_eload — validation reference
get_elmas(table) ELMAS non-residential load curves (GCS) CC BY 4.0 polars DataFrame building_eload — non-residential model
get_occupant_diaries() synthetic occupant activity calendar (GCS) maintainers' synthetic artifact; derived from a restricted-access survey polars DataFrame building_eload — occupancy models
get_activity_library(table) activitymodel diary library from the INSEE time-use survey (GCS) maintainers' derived artifact, no survey identifier; derived from a restricted-access survey polars DataFrame building_eload — occupant calendars via activitymodel
get_elecdom() Enedis panel Elecdom end-use load curves (GCS) Licence Ouverte 2.0 polars DataFrame provenance only — source of building_eload constants
get_bdtopo(iris_code) IGN Géoplateforme WFS (live) or bulk cache Licence Ouverte 2.0 geopandas GeoDataFrame building_eload → buildingmodel — input geometry
get_era5_climate(lat, lon, year) Copernicus CDS (live) or bulk cache CC BY 4.0 (CDS account required) path to EPW file (hour axis UTC by default, see timezone=) buildingmodel — weather boundary condition

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.

Metadata

Release files for buildingdata 0.11.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for buildingdata 0.11.2
File Size Uploaded Provenance Actions
buildingdata-0.11.2.tar.gz 102.6 kB Without provenance Details for buildingdata-0.11.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for buildingdata 0.11.2
File Interpreter ABI Platform Actions
buildingdata-0.11.2-py3-none-any.whl Python 3 none any Details for buildingdata-0.11.2-py3-none-any.whl

Total release size: 222.7 kB

Release files / buildingdata-0.11.2.tar.gz

Download URL buildingdata-0.11.2.tar.gz
Size 102.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f329a51075b516cc4946ec6e55cad2239ab30d3f8eb2489f0e6e1334d46f5e01
BLAKE2b-256 checksum
How to use checksums
133beb06f2f43642f7a40c7a3a02b85d10facefdd42ffba9be1ce7b8daab9e9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / buildingdata-0.11.2-py3-none-any.whl

Download URL buildingdata-0.11.2-py3-none-any.whl
Size 120.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b7df2e90df93d33963fc38a2c5a1f9fdaa591e8d3b96b8b22216fe0e20d311a9
BLAKE2b-256 checksum
How to use checksums
ef44b140c3b3489c25076b0713c77ba151f5a1c350b3ff245fb036965a5d31fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for buildingdata 0.11.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page