czso

Python wrapper around Open Data from the Czech Statistical Office (CZSO).

The real credit goes to CZSO for publishing hundreds of machine-readable datasets with proper metadata and codelists.

Inspired by the R package by Petr Bouchal: petrbouchal/czso

Installation

pip install czso

Or with uv:

uv add czso

Quick start

📓 See demo.ipynb for an interactive walkthrough — browse the catalogue, download datasets, plot wages over time, and explore codelists.

import czso

# Browse available datasets
catalogue = czso.get_catalogue()
print(catalogue[["dataset_id", "title"]].head())

# Download a dataset as a DataFrame
df = czso.get_table("110079")

# Get dataset with metadata
df, meta = czso.get_table("110079", include_metadata=True)
print(meta["title"])

# Get raw (uncleaned) data
df_raw = czso.get_table("110079", clean=False)

# Retrieve a codelist (číselník)
codelist = czso.get_codelist(100)

API

get_table options

• resource_num — which resource to download (default 0)
• force_redownload — skip cache and re-download
• dest_dir — directory for caching downloaded files
• clean — drop code columns, rename to friendly names (default True)
• include_metadata — return (DataFrame, metadata_dict) tuple

AI coding skill

This repo includes a skill that teaches AI coding agents how to use the czso package. Install it with:

npx skills add https://github.com/Marigold/czso --skill czso-data

Related projects

• mcp-csu — MCP server for the CZSO DataStat API. Gives AI assistants (Claude, etc.) direct access to 700+ statistical datasets. Run with uvx mcp-csu.
• petrbouchal/czso — R package for CZSO open data (the inspiration for this project).

Development

make .venv          # install all deps (including dev: ruff, ty, pytest)
make format         # auto-format with ruff
make lint           # lint + fix with ruff
make check-typing   # typecheck with ty
make test           # format + lint + typecheck + unit tests

License

MIT