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 (MIT).

What it covers¶

pytuik speaks to the three public TUIK services, each behind its own quirks:

Service	What you get	Functions
Statistical portal (`veriportali`)	Theme tree: tables, file downloads, press releases, reports, legacy database links	`get_themes`, `get_resources`, `get_tables`, `get_databases`
SDMX NSI service (`nsiws`)	Observations and data structures for every published dataflow	`get_data`, `get_data_structure`
Geographic portal (`cip`)	Regional indicator catalog, indicator values, NUTS-2/3, LAU-1 and settlement boundaries	`geo_variables`, `geo_data`, `geo_map`

The awkward parts are handled for you: the cookie "session dance" the statistical portal requires before it answers an API call, retries with backoff on 5xx and timeouts (never on 4xx), a TTL cache for the two documents almost every call needs, and the repair of TUIK's array-wrapped — and therefore invalid — GeoJSON.

Install¶

pip install pytuik           # core
pip install "pytuik[geo]"    # + geopandas, for geo_map(geometry=True)

Requires Python ≥ 3.10. Core dependencies: httpx, pandas, sdmx1, lxml.

Sixty-second tour¶

import pytuik

pytuik.get_themes()                                    # theme_name, theme_id
pytuik.get_tables(theme=101)                           # tables under a theme
pytuik.get_data("TR,DF_ADNKS_T26,1.0", start="2020")   # tidy long observations
pytuik.geo_map(level=3, geometry=False)                # 81 provinces, attributes only

Every tabular result is a pandas.DataFrame with the same column names tuikr uses, so notes and mental models transfer between the two packages.

Where to next¶

Quickstart — statistical data: theme tree → table → SDMX observations, including how to recover when key="ALL" is rejected.
Quickstart — geographic data: indicator catalog → values → choropleth.
API reference: every public function and class.

Known limitations¶

Verified against the live services on 2026-08-10:

The SDMX service refuses anonymous callers. Every request to nsiws.tuik.gov.tr/rest currently answers 401 Unauthorized, which makes get_data and get_data_structure raise TuikSDMXError with an explanation. The URLs and parsers are unchanged and correct; access is the blocker, and it may be network-dependent — try it from your own connection. The statistical portal and the geographic portal are unaffected.
Geographic level 5 is not supported. A handful of indicators advertise a level 5 alongside 2/3/4; geo_data accepts only {2, 3, 4} (and geo_map additionally 9), because there is no level-5 boundary file to join against. No indicator is published at level 5 only, so nothing is unreachable.
Some published polygons are self-intersecting — 4 of the 81 provinces and 1 of the 973 districts. That is upstream data quality; run gdf.geometry.make_valid() if your workflow needs strictly valid geometries.
Attribute columns differ by level. Only NUTS-3 carries nutsKodu; levels 2 and 4 return code, bolgeKodu, ad.

Stability¶

Versioning is SemVer; the public API is unstable until 1.0. TUIK publishes no versioned API contract, so upstream shapes can change without notice — a weekly contract-test job runs against the live services as an early-warning system.