API Clients¶

Note

For most users, the access layer is recommended. This section documents the low-level API client interface that returns raw dictionaries. The access layer (documented in Access Layer) returns pandas DataFrames and is easier to use for data analysis.

Use the API layer (bdl.api.*) when you need: - Raw API response structure - Custom response processing - Direct access to API metadata - Integration with non-pandas workflows

Use the access layer (bdl.*) when you need: - Pandas DataFrames for data analysis - Automatic column normalization and type inference - Nested data flattening

The pyBDL library provides a comprehensive set of API clients for interacting with the Local Data Bank (BDL) API. All API endpoints are accessible through the main client’s .api attribute. See Main Client for details about the main client.

Available API Endpoints¶
Endpoint	Class	Description
Aggregates	`pybdl.api.aggregates.AggregatesAPI`	Aggregation level metadata and details
Attributes	`pybdl.api.attributes.AttributesAPI`	Attribute metadata and details
Data	`pybdl.api.data.DataAPI`	Statistical data access (variables, units, localities)
Levels	`pybdl.api.levels.LevelsAPI`	Administrative unit aggregation levels
Measures	`pybdl.api.measures.MeasuresAPI`	Measure unit metadata
Subjects	`pybdl.api.subjects.SubjectsAPI`	Subject hierarchy and metadata
Units	`pybdl.api.units.UnitsAPI`	Administrative unit metadata
Variables	`pybdl.api.variables.VariablesAPI`	Variable metadata and details
Version	`pybdl.api.version.VersionAPI`	API version and build info
Years	`pybdl.api.years.YearsAPI`	Available years for data

Note

All API clients are accessible via bdl.api.<endpoint> (e.g., bdl.api.data.get_data_by_variable(...)).

Async Usage¶

All API clients support async methods for high-performance and concurrent applications. Async methods are named with an a prefix (e.g., aget_data_by_variable).

import asyncio
from pybdl import BDL

async def main():
    bdl = BDL()
    data = await bdl.api.data.aget_data_by_variable(variable_id="3643", years=[2021])
    print(data)

asyncio.run(main())

Note

Async methods are available for all endpoints. See the API reference below for details.

Format and Language Parameters¶

API clients support format and language parameters for controlling response content:

Format Options (FormatLiteral): - "json" - JSON format (default) - "jsonapi" - JSON:API format - "xml" - XML format

Language Options (LanguageLiteral): - "pl" - Polish (default if configured) - "en" - English

The format and language parameters automatically set the appropriate HTTP headers: - Accept header is set based on the format parameter - Accept-Language header is set based on the language parameter

from pybdl import BDL

bdl = BDL()

# Request data in XML format
data = bdl.api.data.get_data_by_variable(
    variable_id="3643",
    years=[2021],
    format="xml"
)

# Request data in Polish
data = bdl.api.data.get_data_by_variable(
    variable_id="3643",
    years=[2021],
    lang="pl"
)

Aggregates¶

class pybdl.api.aggregates.AggregatesAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /aggregates endpoints.

Provides access to aggregation level metadata, listing and detail of aggregates, and aggregates API metadata within the Local Data Bank (BDL).

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_aggregate(aggregate_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata details for a specific aggregate.

Maps to: GET /aggregates/{id}

Parameters:

aggregate_id – Aggregate identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with aggregate metadata.

async aget_aggregates_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously list all aggregates metadata.

Maps to: GET /aggregates/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with aggregate metadata.

async alist_aggregates(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously list all aggregates, optionally sorted.

Maps to: GET /aggregates

Parameters:

sort – Sorting order, e.g., ‘Id’, ‘-Id’, ‘Name’, ‘-Name’, etc.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of aggregate metadata dictionaries.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_aggregate(aggregate_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata details for a specific aggregate.

Maps to: GET /aggregates/{id}

Parameters:

aggregate_id – Aggregate identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with aggregate metadata.

get_aggregates_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

List all aggregates metadata.

Maps to: GET /aggregates/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with aggregate metadata.

list_aggregates(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

List all aggregates, optionally sorted.

Maps to: GET /aggregates

Parameters:

sort – Sorting order, e.g., ‘Id’, ‘-Id’, ‘Name’, ‘-Name’, etc.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of aggregate metadata dictionaries.

Attributes¶

class pybdl.api.attributes.AttributesAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /attributes endpoints.

Provides paginated, filterable access to attribute metadata, attribute details, and API metadata for attributes in the Local Data Bank (BDL).

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_attribute(attribute_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata details for a specific attribute.

Maps to: GET /attributes/{id}

Parameters:

attribute_id – Attribute identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with attribute metadata.

async aget_attributes_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /attributes endpoint.

Maps to: GET /attributes/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with API metadata and versioning info.

async alist_attributes(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously list all attributes, optionally filtered by variable.

Maps to: GET /attributes

Parameters:

sort – Optional sorting order.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of attribute metadata dictionaries.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_attribute(attribute_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata details for a specific attribute.

Maps to: GET /attributes/{id}

Parameters:

attribute_id – Attribute identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with attribute metadata.

get_attributes_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /attributes endpoint.

Maps to: GET /attributes/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with API metadata and versioning info.

list_attributes(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

List all attributes, optionally filtered by variable.

Maps to: GET /attributes

Parameters:

sort – Optional sorting order.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of attribute metadata dictionaries.

Data¶

class pybdl.api.data.DataAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for all BDL /data endpoints.

Provides Pythonic, paginated, and DataFrame-ready access to all public data endpoints in the Local Data Bank (BDL) API. Supports flexible parameterization, pagination, and format options for robust data retrieval.

Methods map directly to documented BDL endpoints under the /data namespace, enabling users to fetch statistical data by variable, unit, and locality.

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_data_by_unit(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

async aget_data_by_unit(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Asynchronously retrieve statistical data for a specific administrative unit.

Maps to: GET /data/by-unit/{unit-id}

Parameters:

unit_id – Identifier of the administrative unit.
variable_id – List of variable IDs (required).
years – Optional list of years to filter by.
aggregate_id – Optional aggregate ID.
page – Optional page number to fetch.
page_size – Number of results per page.
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

async aget_data_by_unit_locality(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

async aget_data_by_unit_locality(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Asynchronously retrieve data for a single statistical locality by unit.

Maps to: GET /data/localities/by-unit/{unit-id}

Parameters:

unit_id – Identifier of the statistical locality.
variable_id – List of variable IDs (required).
years – Optional list of years to filter by.
aggregate_id – Optional aggregate ID.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

async aget_data_by_variable(variable_id: str, years: list[int] | None = None, unit_parent_id: str | None = None, unit_level: int | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

async aget_data_by_variable(variable_id: str, years: list[int] | None = None, unit_parent_id: str | None = None, unit_level: int | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Asynchronously retrieve statistical data for a specific variable.

Maps to: GET /data/by-variable/{var-id}

Parameters:

variable_id – Identifier of the variable.
years – Optional list of years to filter by.
unit_parent_id – Optional parent administrative unit ID.
unit_level – Optional administrative unit aggregation level.
aggregate_id – Optional aggregate ID.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

async aget_data_by_variable_locality(variable_id: str, unit_parent_id: str, years: list[int] | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

async aget_data_by_variable_locality(variable_id: str, unit_parent_id: str, years: list[int] | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Asynchronously retrieve data for statistical localities for a single variable.

Maps to: GET /data/localities/by-variable/{var-id}

Parameters:

variable_id – Identifier of the variable.
unit_parent_id – Parent unit ID (required).
years – Optional list of years to filter by.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

async aget_data_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata for the /data endpoint.

Maps to: GET /data/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Metadata describing the /data resource, fields, and parameters.

Return type:

dict

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_data_by_unit(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

get_data_by_unit(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Retrieve statistical data for a specific administrative unit.

Maps to: GET /data/by-unit/{unit-id}

Parameters:

unit_id – Identifier of the administrative unit.
variable_id – List of variable IDs (required).
years – Optional list of years to filter by.
aggregate_id – Optional aggregate ID.
page – Optional page number to fetch.
page_size – Number of results per page.
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

get_data_by_unit_locality(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

get_data_by_unit_locality(unit_id: str, variable_id: list[int], years: list[int] | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Retrieve data for a single statistical locality by unit.

Maps to: GET /data/localities/by-unit/{unit-id}

Parameters:

unit_id – Identifier of the statistical locality.
variable_id – List of variable IDs (required).
years – Optional list of years to filter by.
aggregate_id – Optional aggregate ID.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

get_data_by_variable(variable_id: str, years: list[int] | None = None, unit_parent_id: str | None = None, unit_level: int | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

get_data_by_variable(variable_id: str, years: list[int] | None = None, unit_parent_id: str | None = None, unit_level: int | None = None, aggregate_id: int | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Retrieve statistical data for a specific variable.

Maps to: GET /data/by-variable/{var-id}

Parameters:

variable_id – Identifier of the variable.
years – Optional list of years to filter by.
unit_parent_id – Optional parent administrative unit ID.
unit_level – Optional administrative unit aggregation level.
aggregate_id – Optional aggregate ID.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

get_data_by_variable_locality(variable_id: str, unit_parent_id: str, years: list[int] | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[True] = True) → tuple[list[dict[str, Any]], dict[str, Any]][source]

get_data_by_variable_locality(variable_id: str, unit_parent_id: str, years: list[int] | None = None, page: int | None = None, page_size: int = 100, max_pages: int | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, lang: Literal['pl', 'en'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None, return_metadata: Literal[False] = False) → list[dict[str, Any]]

Retrieve data for statistical localities for a single variable.

Maps to: GET /data/localities/by-variable/{var-id}

Parameters:

variable_id – Identifier of the variable.
unit_parent_id – Parent unit ID (required).
years – Optional list of years to filter by.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
format – Expected response content type (defaults to config.format).
lang – Expected response content language (defaults to config.language).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.
return_metadata – If True, include metadata in the response.

Returns:

List of results, optionally with metadata dict.

get_data_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata for the /data endpoint.

Maps to: GET /data/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Metadata describing the /data resource, fields, and parameters.

Return type:

dict

Levels¶

class pybdl.api.levels.LevelsAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /levels endpoints.

Provides access to administrative unit aggregation levels and their metadata in the Local Data Bank (BDL).

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_level(level_id: int, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata for a specific aggregation level.

Maps to: GET /levels/{id}

Parameters:

level_id – Aggregation level identifier (integer).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with level metadata.

async aget_levels_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /levels endpoint.

Maps to: GET /levels/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with API metadata and versioning info.

async alist_levels(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously list all administrative unit aggregation levels.

Maps to: GET /levels

Parameters:

sort – Optional sorting order, e.g., ‘Id’, ‘-Id’, ‘Name’, ‘-Name’.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of aggregation level metadata dictionaries.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_level(level_id: int, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata for a specific aggregation level.

Maps to: GET /levels/{id}

Parameters:

level_id – Aggregation level identifier (integer).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with level metadata.

get_levels_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /levels endpoint.

Maps to: GET /levels/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with API metadata and versioning info.

list_levels(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

List all administrative unit aggregation levels.

Maps to: GET /levels

Parameters:

sort – Optional sorting order, e.g., ‘Id’, ‘-Id’, ‘Name’, ‘-Name’.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of aggregation level metadata dictionaries.

Measures¶

class pybdl.api.measures.MeasuresAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /measures endpoints.

Provides access to measure unit metadata (e.g. “number”, “percent”, “kg”) used for variables in the Local Data Bank (BDL).

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_measure(measure_id: int, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata for a specific measure unit.

Maps to: GET /measures/{id}

Parameters:

measure_id – Measure unit identifier (integer).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with measure unit metadata.

async aget_measures_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /measures endpoint.

Maps to: GET /measures/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

async alist_measures(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously list all measure units, optionally sorted.

Maps to: GET /measures

Parameters:

sort – Optional sorting order, e.g. ‘Id’, ‘-Id’, ‘Name’, ‘-Name’.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of measure unit metadata dictionaries.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_measure(measure_id: int, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata for a specific measure unit.

Maps to: GET /measures/{id}

Parameters:

measure_id – Measure unit identifier (integer).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with measure unit metadata.

get_measures_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /measures endpoint.

Maps to: GET /measures/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

list_measures(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

List all measure units, optionally sorted.

Maps to: GET /measures

Parameters:

sort – Optional sorting order, e.g. ‘Id’, ‘-Id’, ‘Name’, ‘-Name’.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of measure unit metadata dictionaries.

Subjects¶

class pybdl.api.subjects.SubjectsAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /subjects endpoints.

Provides access to the subject hierarchy (thematic areas) in the Local Data Bank (BDL), including subject browsing, detail retrieval, and metadata.

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_subject(subject_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata for a specific subject.

Maps to: GET /subjects/{id}

Parameters:

subject_id – Subject identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with subject metadata.

async aget_subjects_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /subjects endpoint.

Maps to: GET /subjects/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

Asynchronously list all subjects, optionally filtered by parent subject.

Maps to: GET /subjects

Parameters:

parent_id – Optional parent subject ID. If not specified, returns all top-level subjects.
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of subject metadata dictionaries.

async asearch_subjects(name: str, page: int | None = None, page_size: int = 100, max_pages: int | None = None, sort: str | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously search for subjects by name.

Maps to: GET /subjects/search

Parameters:

name – Subject name to search for (required).
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of subject metadata dictionaries matching the search.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_subject(subject_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata for a specific subject.

Maps to: GET /subjects/{id}

Parameters:

subject_id – Subject identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with subject metadata.

get_subjects_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /subjects endpoint.

Maps to: GET /subjects/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

List all subjects, optionally filtered by parent subject.

Maps to: GET /subjects

Parameters:

parent_id – Optional parent subject ID. If not specified, returns all top-level subjects.
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of subject metadata dictionaries.

search_subjects(name: str, page: int | None = None, page_size: int = 100, max_pages: int | None = None, sort: str | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Search for subjects by name.

Maps to: GET /subjects/search

Parameters:

name – Subject name to search for (required).
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of subject metadata dictionaries matching the search.

Units¶

class pybdl.api.units.UnitsAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /units endpoints.

Provides access to administrative unit metadata in the Local Data Bank (BDL), including listing units (with filtering by level, parent, etc.), retrieving unit details, and accessing general units API metadata.

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_locality(locality_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata details for a specific statistical locality.

Maps to: GET /units/localities/{id}

Parameters:

locality_id – Locality identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with locality metadata.

async aget_unit(unit_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata details for a specific administrative unit.

Maps to: GET /units/{id}

Parameters:

unit_id – Administrative unit identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with unit metadata.

async aget_units_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /units endpoint.

Maps to: GET /units/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

async alist_localities(parent_id: str, page: int | None = None, page_size: int = 100, max_pages: int | None = None, sort: str | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously list all statistical localities, optionally filtered by parent.

Maps to: GET /units/localities

Parameters:

parent_id – Parent unit ID (required).
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of locality metadata dictionaries.

Asynchronously list all administrative units, optionally filtered by level, parent, or name.

Maps to: GET /units

Parameters:

parent_id – Optional parent unit ID.
level – Optional list of administrative levels to filter by.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of unit metadata dictionaries.

Asynchronously search for statistical localities by name and optional filters.

Maps to: GET /units/localities/search

Parameters:

name – Optional substring to search in locality name.
years – Optional list of years to filter by.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of locality metadata dictionaries.

Asynchronously search for administrative units by name and optional filters.

Maps to: GET /units/search

Parameters:

name – Optional substring to search in unit name.
level – Optional list of administrative levels to filter by.
years – Optional list of years to filter by.
kind – Optional kind filter.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of unit metadata dictionaries.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_locality(locality_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata details for a specific statistical locality.

Maps to: GET /units/localities/{id}

Parameters:

locality_id – Locality identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with locality metadata.

get_unit(unit_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata details for a specific administrative unit.

Maps to: GET /units/{id}

Parameters:

unit_id – Administrative unit identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with unit metadata.

get_units_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /units endpoint.

Maps to: GET /units/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

list_localities(parent_id: str, page: int | None = None, page_size: int = 100, max_pages: int | None = None, sort: str | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

List all statistical localities, optionally filtered by parent.

Maps to: GET /units/localities

Parameters:

parent_id – Parent unit ID (required).
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of locality metadata dictionaries.

List all administrative units, optionally filtered by level, parent, or name.

Maps to: GET /units

Parameters:

parent_id – Optional parent unit ID.
level – Optional list of administrative levels to filter by.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of unit metadata dictionaries.

Search for statistical localities by name and optional filters.

Maps to: GET /units/localities/search

Parameters:

name – Optional substring to search in locality name.
years – Optional list of years to filter by.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of locality metadata dictionaries.

Search for administrative units by name and optional filters.

Maps to: GET /units/search

Parameters:

name – Optional substring to search in unit name.
level – Optional list of administrative levels to filter by.
years – Optional list of years to filter by.
kind – Optional kind filter.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of unit metadata dictionaries.

Variables¶

class pybdl.api.variables.VariablesAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /variables endpoints.

Provides access to variable metadata in the Local Data Bank (BDL), including listing variables (with filtering by category or aggregate), retrieving variable details, and accessing general variables API metadata.

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_variable(variable_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata details for a specific variable.

Maps to: GET /variables/{id}

Parameters:

variable_id – Variable identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with variable metadata.

async aget_variables_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /variables endpoint.

Maps to: GET /variables/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

Asynchronously list all variables, optionally filtered by subject, level, or year.

Maps to: GET /variables

Parameters:

subject_id – Optional subject ID to filter variables.
level – Optional level to filter variables.
years – Optional list of years to filter variables.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of variable metadata dictionaries.

Asynchronously search for variables by name and optional filters.

Maps to: GET /variables/search

Parameters:

name – Optional substring to search in variable name.
subject_id – Optional subject ID to filter variables.
level – Optional level to filter variables.
years – Optional list of years to filter variables.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of variable metadata dictionaries.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_variable(variable_id: str, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata details for a specific variable.

Maps to: GET /variables/{id}

Parameters:

variable_id – Variable identifier.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with variable metadata.

get_variables_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /variables endpoint.

Maps to: GET /variables/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

List all variables, optionally filtered by subject, level, or year.

Maps to: GET /variables

Parameters:

subject_id – Optional subject ID to filter variables.
level – Optional level to filter variables.
years – Optional list of years to filter variables.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order, e.g. ‘id’, ‘-id’, ‘name’, ‘-name’.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of variable metadata dictionaries.

Search for variables by name and optional filters.

Maps to: GET /variables/search

Parameters:

name – Optional substring to search in variable name.
subject_id – Optional subject ID to filter variables.
level – Optional level to filter variables.
years – Optional list of years to filter variables.
page – Optional page number to fetch.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all pages, 1 for single page).
sort – Optional sorting order.
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of variable metadata dictionaries.

Version¶

class pybdl.api.version.VersionAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /version endpoint.

Provides access to version and build information for the Local Data Bank (BDL) API.

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_version(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve the API version and build information.

Maps to: GET /version

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format). Note: only “json” and “xml” are supported for this endpoint.
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with version and build metadata.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

Retrieve the API version and build information.

Maps to: GET /version

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format). Note: only “json” and “xml” are supported for this endpoint.
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with version and build metadata.

Years¶

class pybdl.api.years.YearsAPI(config: BDLConfig, extra_headers: dict[str, str] | None = None)[source]

Bases: BaseAPIClient

Client for the BDL /years endpoints.

Provides access to available data years in the Local Data Bank (BDL), including listing all years, retrieving year details, and accessing years API metadata.

async afetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch paginated results and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

async afetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Asynchronously fetch a single result, non-paginated.

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

async aget_year(year_id: int, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve metadata for a specific year.

Maps to: GET /years/{id}

Parameters:

year_id – Year identifier (integer, e.g. 2020).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with year metadata.

async aget_years_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Asynchronously retrieve general metadata and version information for the /years endpoint.

Maps to: GET /years/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

async alist_years(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

Asynchronously list all available years for which data is present in the BDL API.

Maps to: GET /years

Parameters:

sort – Optional sort parameter.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of available years as dicts.

fetch_all_results(endpoint: str, *, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, results_key: str = 'results', page_size: int = 100, max_pages: int | None = None, return_metadata: bool = False, show_progress: bool = True) → list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]]

Fetch paginated results synchronously and combine them into a single list.

Parameters:

endpoint – API endpoint.
method – HTTP method (default: GET).
params – Query parameters.
headers – Optional request headers.
results_key – Key for extracting data from each page.
page_size – Items per page.
max_pages – Optional limit of pages.
return_metadata – If True, return (results, metadata).
show_progress – Display progress via tqdm.

Returns:

Combined list of results, optionally with metadata.

fetch_single_result(endpoint: str, *, results_key: str | None = None, method: str = 'GET', params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, return_metadata: bool = False) → dict[str, Any] | list[dict[str, Any]] | tuple[list[dict[str, Any]], dict[str, Any]] | tuple[dict[str, Any], dict[str, Any]]

Fetch a single result, non-paginated (sync).

Parameters:

endpoint – API endpoint.
results_key – If not None, extract this key from the JSON.
method – HTTP method.
params – Query parameters.
headers – Optional request headers.
return_metadata – Also return metadata if True.

Returns:

Dictionary or list, optionally with separate metadata.

get_year(year_id: int, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve metadata for a specific year.

Maps to: GET /years/{id}

Parameters:

year_id – Year identifier (integer, e.g. 2020).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with year metadata.

get_years_metadata(lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → dict[str, Any][source]

Retrieve general metadata and version information for the /years endpoint.

Maps to: GET /years/metadata

Parameters:

lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

Dictionary with endpoint metadata and versioning info.

list_years(sort: str | None = None, page_size: int = 100, max_pages: int | None = None, lang: Literal['pl', 'en'] | None = None, format: Literal['json', 'jsonapi', 'xml'] | None = None, if_none_match: str | None = None, if_modified_since: str | None = None, extra_query: dict[str, Any] | None = None) → list[dict[str, Any]][source]

List all available years for which data is present in the BDL API.

Maps to: GET /years

Parameters:

sort – Optional sort parameter.
page_size – Number of results per page.
max_pages – Maximum number of pages to fetch (None for all).
lang – Expected response content language (defaults to config.language).
format – Expected response content type (defaults to config.format).
if_none_match – Conditional request header If-None-Match (entity tag).
if_modified_since – Conditional request header If-Modified-Since.
extra_query – Additional query parameters.

Returns:

List of available years as dicts.

API Clients¶

Async Usage¶

Format and Language Parameters¶

Aggregates¶

Attributes¶

Data¶

Levels¶

Measures¶

Subjects¶

Units¶

Variables¶

Version¶

Years¶

pyBDL

Navigation

Related Topics