pyBDL documentation

What is the Local Data Bank (BDL)?

The Local Data Bank (BDL, Bank Danych Lokalnych) is Poland’s official statistical data warehouse, maintained by Statistics Poland (GUS). It provides access to a vast range of statistical indicators and datasets covering:

• Demographics and population

• Economy and labor market

• Education, health, and social welfare

• Environment and infrastructure

• Regional and local statistics (down to municipality level)

• Historical time series and more

Data is available for various administrative units (country, voivodeship, county, municipality) and can be filtered by year, subject, and other attributes. The BDL is a primary source for open, official statistics in Poland.

For a full description of available data, endpoints, and API usage, see:

• Official BDL API documentation: https://api.stat.gov.pl/Home/BdlApi

• BDL web portal: https://bdl.stat.gov.pl/bdl/start

pyBDL is a modern, Pythonic client library for the Local Data Bank (BDL, Bank Danych Lokalnych) API, enabling easy, robust access to Polish official statistics for data science, research, and applications.

Features

• Clean, modular API client for all BDL endpoints

• Pandas DataFrame integration for tabular data

• Full support for pagination, filtering, and internationalization

• Built-in API key, language, and cache configuration

• Open source, tested, and ready for data analysis and visualization

Quick Start

from pybdl import BDL, BDLConfig

# Initialize client
bdl = BDL(BDLConfig(api_key="your-api-key"))  # Reads config from environment or defaults

# Use the access layer (returns pandas DataFrames)
df = bdl.data.get_data_by_variable(variable_id="3643", years=[2021])
print(df.head())

# Data is ready for analysis
print(df.dtypes)
print(df.columns)

Configuration

Configure your API key and options via environment variables or directly:

from pybdl import BDLConfig
config = BDLConfig(api_key="your-api-key", language="en", use_cache=True)
bdl = BDL(config=config)

Or set environment variables:

export BDL_API_KEY=your-api-key
export BDL_LANGUAGE=en

Documentation

User Guide

• Main Client
  • Access Layer (Default Interface)
  • API Layer (Low-Level Interface)
  • Examples
• Access Layer
  • Overview
  • Quick Start
  • Key Features
  • Available Endpoints
  • Endpoint Details
  • Pagination
  • Async Usage
  • Examples
  • API Reference
• Examples
  • Basic Data Retrieval
  • Population Analysis by Region
  • Economic Indicator Comparison
  • Time Series Analysis
  • Error Handling
  • Best Practices
• API Clients
  • Async Usage
  • Format and Language Parameters
• Configuration
  • Common Configuration Scenarios
  • Environment Variables
  • Caching
  • Proxy Configuration
  • Rate Limiting & Quotas
• Rate Limiting
  • Overview
  • Key Features
  • Default Quotas
  • User Guide
  • Technical Details
  • API Reference
  • Examples
  • Best Practices
  • Troubleshooting

Reference

• Appendix: Technical Implementation Details
  • Rate Limiting Implementation
  • Configuration Implementation Details
  • Access Layer Implementation
  • API Client Architecture

Contributing & License

pyBDL is open source under the MIT license. Contributions and issues are welcome! For details, see the GitHub repository.