Metadata-Version: 2.4
Name: pytuik
Version: 0.1.0
Summary: Unofficial Python client for Turkish Statistical Institute (TUIK) public data portals
Project-URL: Homepage, https://github.com/gohnJalt/pytuik
Project-URL: Documentation, https://gohnjalt.github.io/pytuik/
Project-URL: Repository, https://github.com/gohnJalt/pytuik
Project-URL: Changelog, https://github.com/gohnJalt/pytuik/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/gohnJalt/pytuik/issues
Project-URL: Reference implementation, https://github.com/emraher/tuikr
Author: Kaan Akkaş
License: MIT
License-File: LICENSE
Keywords: opendata,sdmx,statistics,tuik,turkey
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: lxml>=4.9
Requires-Dist: pandas>=2.0
Requires-Dist: sdmx1>=2.15
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: geo
Requires-Dist: geopandas>=0.14; extra == 'geo'
Description-Content-Type: text/markdown

# pytuik

[![CI](https://github.com/gohnJalt/pytuik/actions/workflows/ci.yml/badge.svg)](https://github.com/gohnJalt/pytuik/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pytuik.svg)](https://pypi.org/project/pytuik/)
[![Python](https://img.shields.io/pypi/pyversions/pytuik.svg)](https://pypi.org/project/pytuik/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Unofficial Python client for the Turkish Statistical Institute (TUIK) public data
portals. A faithful rewrite of the R package
[emraher/tuikr](https://github.com/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

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

Requires Python ≥ 3.10.

## What you get

| Service | Functions |
|---|---|
| Statistical portal (`veriportali`) | `get_themes`, `get_resources`, `get_tables`, `get_databases` |
| SDMX NSI service (`nsiws`) | `get_data`, `get_data_structure` |
| Geographic portal (`cip`) | `geo_variables`, `geo_data`, `geo_map` |

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

```python
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](https://gohnjalt.github.io/pytuik/#known-limitations).

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

```python
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:

```python
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](https://gohnjalt.github.io/pytuik/quickstart/)
· [geographic data](https://gohnjalt.github.io/pytuik/geographic/).

## Development

```bash
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](CONTRIBUTING.md) for the architecture rules and release
process, and [DESIGN.md](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](CITATION.cff) — and
please cite `tuikr` as well.

## License

MIT — see [LICENSE](LICENSE). `tuikr` is likewise MIT licensed.
