tuiksdmx Brings TÜİK SDMX Metadata and Data Retrieval Into R

For analysts working with Turkish official statistics, the hard part of an API request often comes before downloading any data: identifying the right dataset, learning its dimensions and choosing valid codes. The R package tuiksdmx addresses that work by bringing dataset discovery, metadata inspection, filter validation and observation retrieval into a single workflow for the Turkish Statistical Institute’s (TÜİK, or TurkStat) SDMX REST service.

That design matters because SDMX datasets are structured around more than rows and columns. Each Dataflow is linked to a Data Structure Definition (DSD), which specifies its dimensions. Codelists describe permitted values for those dimensions, while Concepts explain what they mean. A request can be syntactically plausible yet target the wrong categories or return a broader set of observations than expected. The package’s focus is making those choices easier to inspect before a request goes to the service.

Metadata first, observations second

The package supports a sequence that begins with discovery rather than a manually assembled endpoint. Analysts can search TÜİK Dataflows by subject in English or Turkish, inspect a Dataflow’s structure, review its dimensions and associated codes, then build a request. The aim is to make the reasoning behind a query visible and repeatable, rather than leaving users to infer SDMX keys from raw service details.

For example, an English-language search for consumer prices can return matching Dataflows without requiring the user to know an identifier in advance:

flows <- tuik_search_dataflows(
  "consumer price",
  language = "en",
  limit = 10
)
flows

Search can also use Turkish terms, such as tuik_search_dataflows("tüketici fiyat"). Once a candidate is identified, tuik_explore() can show its structure or inspect a particular dimension. The source article uses the consumer price Dataflow DF_TUFE_SDMX_TT01 as an example and cautions that provider metadata can change, so production workflows should check the current structure.

tuik_explore("DF_TUFE_SDMX_TT01")
tuik_explore(
  "DF_TUFE_SDMX_TT01",
  dimension = "DEGISIM"
)

That inspection step has practical value: it can reveal whether the dimension names and codes in a planned request match the provider’s current metadata. It also helps separate two questions that are easy to conflate: whether a code is allowed by the structure, and whether observations for that code are actually present in the requested data.

Retrieval requires attention to query scope

Version 0.1.0 is available through GitHub and is not currently on CRAN. Installation uses pak:

install.packages("pak") # If needed
pak::pak("MFatihTuzen/tuiksdmx")
library(tuiksdmx)

The TÜİK SDMX data endpoints currently require authentication. Users need their own API key, which the package reads from the TUIK_SDMX_API_KEY environment variable. Storing that credential in a personal .Renviron file keeps it out of scripts and shared repositories; after editing the file, restart R so the environment variable is available.

TUIK_SDMX_API_KEY=YOUR_OWN_API_KEY

A basic retrieval can specify a Dataflow and period:

cpi <- tuik_get_data(
  "DF_TUFE_SDMX_TT01",
  start_period = "2026-01",
  end_period = "2026-01"
)
head(cpi)

But a narrow time window does not necessarily produce a narrow response. This example requests all series for the selected period, not just one CPI indicator. Analysts who need a specific slice can supply named dimension filters, which the package checks against the Dataflow metadata.

selected <- list(
  REF_AREA = "TR",
  FREQ = "M",
  DEGISIM = "1",
  SINIFLAMA_DUZEYI = "2"
)

tuik_explore(
  "DF_TUFE_SDMX_TT01",
  filters = selected
)

There is a meaningful distinction between complete and partial filters. With a complete series key, the package can construct a targeted server-side SDMX request. Partial filters require an explicit allow_all = TRUE opt-in and may involve downloading a broader response before filtering it in R. That option does not set a response-size limit, so users need to consider the likely scope of a query. The project’s filtering and performance guide describes this behavior.

Valid codes aren’t always populated codes

A metadata Codelist describes the values permitted for a dimension. It doesn’t guarantee that every permitted value appears in observations for a given period and filter set. For statistical analysis, that difference can affect category checks, data validation and the interpretation of missing results.

tuiksdmx exposes both sides of the distinction. A flow profile can be used to inspect codes defined in metadata, while tuik_available_codes() can identify codes that appear in observations returned for a bounded request.

profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")

# Codes permitted by the metadata
tuik_dimension_codes(profile, dimension = "DEGISIM")

# Codes observed in a particular request
observed <- tuik_available_codes(
  profile,
  dimension = "COICOP_2018",
  start_period = "2026-01",
  end_period = "2026-01",
  allow_all = TRUE
)
observed

The observed-code result depends on the data retrieved for that request. It is not an SDMX ContentConstraint query, and the example’s use of allow_all = TRUE can lead to a broad download. The distinction gives analysts a clearer basis for interpreting the codes they see: metadata describes what may be valid; returned observations show what is present under the chosen request.

A focused client with a defined scope

The package is an SDMX client for TÜİK’s service, not a general interface to every resource on the institute’s portal. Its initial release does not claim to support every SDMX feature or every Dataflow without further testing. Provider structures and authentication behavior may change, so reproducible analysis still depends on checking metadata and setting sensible request boundaries.

Documentation covers authentication, Dataflow discovery, DSD metadata, filtering, observed availability and code-label decoding. The Getting Started guide and function reference provide entry points to those details.

The project is independently developed and open source; it is not official TÜİK software. Its GitHub repository, package website, guides and issue tracker host the code, documentation and project discussion.

For an API client handling structured statistical data, returning a table is only part of the job. The more useful test is whether an analyst can explain which Dataflow, dimensions and codes shaped the result—and repeat that request later. By putting metadata checks beside retrieval, tuiksdmx makes that audit trail a practical part of the R workflow.