pytuik

Unofficial Python client for the Turkish Statistical Institute (TUIK) public data portals. A faithful rewrite of the R package emraher/tuikr.

Disclaimer: This package is not affiliated with or endorsed by TUIK. It is an independent tool for research use. API design derived from emraher/tuikr.

Documentation: https://gohnjalt.github.io/pytuik/

Install

pip install pytuik           # core
pip install "pytuik[geo]"    # + geopandas for boundary geometries

Requires Python ≥ 3.10.

What you get

The cookie "session dance" the statistical portal demands, retries with backoff on 5xx and timeouts, an in-memory TTL cache, and the repair of TUIK's invalid, array-wrapped GeoJSON are all handled for you. Every tabular result is a pandas.DataFrame using the same column names as tuikr.

Usage

import pytuik

pytuik.get_themes()                                    # theme_name, theme_id
pytuik.get_tables(theme=101)                           # dataflow + istab tables
pytuik.get_data("TR,DF_ADNKS_T26,1.0", start="2020")   # tidy long observations
pytuik.get_data("TR,DF_ADNKS_T26,1.0", labels=False)   # skip the structure request
pytuik.get_data_structure("TR,DF_ADNKS_T26,1.0")       # dimensions + codelists

Heads-up: as of 2026-08-10 TUIK's SDMX service (nsiws.tuik.gov.tr) returns 401 Unauthorized to anonymous callers, so get_data / get_data_structure raise TuikSDMXError. The portal and geographic functions are unaffected. See known limitations.

Geographic portal (geometry=True needs pip install "pytuik[geo]"):

pytuik.geo_variables()                     # indicator catalog
pytuik.geo_data("1000", level=3)           # long form: code, date, <indicator>
pytuik.geo_map(level=3)                    # GeoDataFrame of the 81 provinces
pytuik.geo_map(level=3, geometry=False)    # attributes only, plain pandas

For connection reuse and configuration, use the client the module-level functions delegate to:

from pytuik import TuikClient

with TuikClient(lang="tr", timeout=60.0, retries=5) as client:
    df = client.get_data("TR,DF_ADNKS_T26,1.0", start="2020")

Full walkthroughs: statistical data · geographic data.

Development

pip install -e ".[dev,geo,docs]"
pytest                # unit + mocked client tests (network excluded by default)
pytest -m contract    # opt-in live-network tests
ruff check .
mypy
mkdocs serve          # docs at http://127.0.0.1:8000

See CONTRIBUTING.md for the architecture rules and release process, and DESIGN.md for the upstream API contracts and the reasoning behind each deviation from tuikr.

Citing

If you use pytuik in research, cite it via CITATION.cff — and please cite tuikr as well.

License

MIT — see LICENSE. tuikr is likewise MIT licensed.