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
| 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:
- Explicit function arguments / CLI options
- Environment variables (
BUILDINGDATA_BUCKET,BUILDINGDATA_CACHE_DIR,GOOGLE_APPLICATION_CREDENTIALS) - Global configuration file (
~/.config/buildingdata/config.ini) - 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_DIRenvironment 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.