API reference¶
Everything on this page is importable directly from pytuik. The module-level
functions delegate to a process-wide default client; the identically named
TuikClient methods let you control the session.
Statistical portal¶
pytuik.get_themes ¶
Return all statistical themes (theme_name, theme_id).
pytuik.get_resources ¶
get_resources(theme: int | str, types: Iterable[str] | None = None, lang: str | None = None) -> pd.DataFrame
Return every resource leaf under theme, optionally filtered by types.
pytuik.get_tables ¶
Return downloadable tables (dataflow + istab) under theme.
pytuik.get_databases ¶
Return legacy database links under theme.
SDMX¶
pytuik.get_data ¶
get_data(dataflow_id: str, key: str = 'ALL', *, start: str | None = None, end: str | None = None, detail: str = 'full', dimension_at_observation: str = 'TIME_PERIOD', lang: str | None = None, labels: bool = True, drop_invariant: bool = True) -> pd.DataFrame
Fetch observations for a dataflow as a tidy long DataFrame.
pytuik.get_data_structure ¶
Fetch the dimensions and codelists of a dataflow.
pytuik.DataflowStructure
dataclass
¶
DataflowStructure(dataflow_id: str, dimensions: list[str], label_maps: dict[str, dict[str, str]] = dict(), time_dimension: str = 'TIME_PERIOD')
The subset of a DSD that pytuik needs.
Attributes:
| Name | Type | Description |
|---|---|---|
dataflow_id |
str
|
The |
dimensions |
list[str]
|
Non-time dimension ids in key order — needed to build a narrower key when
|
label_maps |
dict[str, dict[str, str]]
|
|
time_dimension |
str
|
The time dimension id (usually |
Geographic portal¶
pytuik.geo_variables ¶
Return the geographic indicator catalog.
pytuik.geo_data ¶
Return indicator values in long form (code, date, <name>).
pytuik.geo_map ¶
Return administrative boundaries for a level (2/3/4/9).
Client¶
pytuik.TuikClient ¶
TuikClient(lang: str = 'en', *, timeout: float = 30.0, retries: int = 3, cache_ttl: float = 3600.0, user_agent: str | None = None)
A reusable session for all three TUIK services.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lang
|
str
|
Default language ( |
'en'
|
timeout
|
float
|
Per-request timeout in seconds. |
30.0
|
retries
|
int
|
Number of retry attempts for idempotent GETs on connect errors, timeouts, and 5xx responses. Never retries on 4xx. |
3
|
cache_ttl
|
float
|
Seconds to cache the rarely-changing theme tree and sideMenu documents.
|
3600.0
|
user_agent
|
str | None
|
Override the default browser-like User-Agent. |
None
|
get_portal_json ¶
GET a veriportali API endpoint, handling the cookie dance and envelope.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
API path relative to the veriportali base, e.g.
|
required |
lang
|
str
|
Language segment; also gates the session cookie. |
required |
cache
|
bool
|
Whether to serve from / store in the TTL cache. |
True
|
Returns:
| Type | Description |
|---|---|
Any
|
The |
get_json ¶
GET an arbitrary URL and decode JSON (used by the geo portal).
get_bytes ¶
get_bytes(url: str, *, params: dict[str, Any] | None = None, headers: dict[str, str] | None = None) -> bytes
GET an arbitrary URL and return raw bytes (used for SDMX-ML).
get_themes ¶
Return all statistical themes (theme_name, theme_id).
get_resources ¶
get_resources(theme: int | str, types: Iterable[str] | None = None, lang: str | None = None) -> pd.DataFrame
Return every resource leaf under theme, optionally filtered.
get_tables ¶
Return downloadable tables (dataflow + istab) under theme.
get_databases ¶
Return legacy database links under theme.
get_data ¶
get_data(dataflow_id: str, key: str = 'ALL', *, start: str | None = None, end: str | None = None, detail: str = 'full', dimension_at_observation: str = 'TIME_PERIOD', lang: str | None = None, labels: bool = True, drop_invariant: bool = True) -> pd.DataFrame
Fetch observations for a dataflow as a tidy long DataFrame.
get_data_structure ¶
Fetch the dimensions and codelists of a dataflow.
geo_variables ¶
Return the geographic indicator catalog.
geo_data ¶
Return indicator values in long form (code, date, <name>).
geo_map ¶
Return administrative boundaries for a level (2/3/4/9).
pytuik.get_default_client ¶
Return the process-wide default client, creating it on first use.
Thread-safe: the client is created under a lock so concurrent first calls do not race.
pytuik.set_default_client ¶
Replace the process-wide default client (e.g. to reconfigure timeouts).
Exceptions¶
pytuik.TuikError ¶
Bases: Exception
Base class for every error raised by pytuik.
pytuik.TuikHTTPError ¶
Bases: TuikError
A non-2xx HTTP response survived the retry policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable description. |
required |
status_code
|
int | None
|
The HTTP status code of the failing response, when available. |
None
|
url
|
str | None
|
The requested URL. |
None
|
pytuik.TuikPortalError ¶
Bases: TuikError
The veriportali envelope reported isError=True.
Carries the portal-supplied message field.