tuiksdmx

Version 0.1.1 is being prepared for a first CRAN submission. The published GitHub release is v0.1.0; the package is not yet on CRAN. Consult GitHub Releases for published tags and release notes. TÜİK SDMX endpoints require authentication. Dataflow structures and service behaviour may change; examples below use a Dataflow verified during development.

Why tuiksdmx?

SDMX datasets are multidimensional. To construct a meaningful query, you may need to know the Dataflow, its data structure definition (DSD), dimension order, codes and time range. tuiksdmx uses this metadata to make the process easier and more reproducible, without requiring you to manually assemble an SDMX key for ordinary workflows.

The package also offers observed availability: inspect which dimension codes occur in data for a specified request, rather than assuming every code in a codelist has observations.

Installation

Install the current GitHub version using pak (recommended):

install.packages("pak")  # Run once, if not already installed
pak::pak("MFatihTuzen/tuiksdmx")

Alternatively, use remotes, a familiar option for installing R packages from GitHub:

install.packages("remotes")  # Run once, if not already installed
remotes::install_github("MFatihTuzen/tuiksdmx")

Both methods install the current GitHub version; the package is not yet on CRAN. To install the six built vignettes using remotes, use remotes::install_github("MFatihTuzen/tuiksdmx", build_vignettes = TRUE, upgrade = "never"). Then load it:

library(tuiksdmx)

For contributors working from a local source checkout, devtools::load_all() is also available.

Quick start

1. Configure authentication

TÜİK SDMX requests require an API key. For everyday use, store it in your personal .Renviron file (open it with usethis::edit_r_environ() if needed):

TUIK_SDMX_API_KEY=YOUR_OWN_API_KEY

Restart R after saving. The package will read this environment variable automatically. Never commit credentials or paste access tokens into issues, scripts or notebooks.

You can also supply an API key explicitly through api_key or set TUIK_SDMX_API_KEY for the current session; see Authentication options.

2. Discover Dataflows

You do not need to know a Dataflow ID in advance. Browse the authenticated catalogue or search by subject:

# Retrieve the catalogue of Dataflows
flows <- tuik_dataflows()

# View identifiers and their Turkish / English names
head(flows[c("dataflow_id", "name_tr", "name_en")], 10)

# Search the catalogue in Turkish (accent-insensitive matching)
tuik_search_dataflows("tüketici fiyat", limit = 10)

# Or search by English terminology
tuik_search_dataflows("consumer price", language = "en", limit = 10)

Choose a dataflow_id from the results. The remainder of this example uses the CPI Dataflow DF_TUFE_SDMX_TT01, which was inspected during package development; live catalogues can change.

3. Explore a Dataflow

# Inspect dimensions and metadata without retrieving observations
tuik_explore("DF_TUFE_SDMX_TT01")

# List codes and their descriptions for a dimension
tuik_explore("DF_TUFE_SDMX_TT01", dimension = "DEGISIM")

# Search descriptions in another dimension
tuik_explore(
  "DF_TUFE_SDMX_TT01",
  dimension = "COICOP_2018",
  search = "gıda"
)

4. Retrieve observations

If you know the Dataflow ID and time window, you can make a request directly:

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

head(cpi)

This requests all series for the specified observation period. It is not limited to a single CPI indicator.

5. Narrow the result with structured filters

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

# Check the filters against the structure
tuik_explore("DF_TUFE_SDMX_TT01", filters = chosen)

cpi_selected <- tuik_get_data(
  "DF_TUFE_SDMX_TT01",
  filters = chosen,
  start_period = "2026-01",
  end_period = "2026-01",
  allow_all = TRUE,
  labels = "tr"
)

Caution — partial filters can trigger broad downloads. With a partial series key, allow_all = TRUE explicitly permits retrieval of all series within the requested period, followed by local filtering in R. It is not a download-size, memory or time limit. The partial/wildcard key patterns tested during development were not accepted by the TÜİK service. For targeted server-side requests, specify a complete set of series key dimensions.

Time dimension detail: TIME_PERIOD refers to observation time and is controlled with start_period / end_period, not placed in the series-key filters. YAYIM_DONEMI is a separate DSD series dimension.

Metadata, profiles and observed availability

Use a profile when inspecting or querying the same Dataflow repeatedly:

profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")

# Series-key dimensions and their associated codelists
tuik_filter_dimensions(profile)

# Theoretical domain defined by a codelist
tuik_dimension_codes(profile, dimension = "DEGISIM")

# Codes actually present in the returned observations for this request
observed <- tuik_available_codes(
  profile,
  dimension = "COICOP_2018",
  filters = list(
    REF_AREA = "TR",
    FREQ = "M",
    SINIFLAMA_DUZEYI = "2",
    DEGISIM = "1"
  ),
  start_period = "2026-01",
  end_period = "2026-01",
  allow_all = TRUE
)

observed

Codelist domain ≠ observed availability. A codelist describes permissible codes; tuik_available_codes() derives observed codes from retrieved observations for the specified request. It does not implement SDMX ContentConstraint queries.

Authentication

Users require their own credentials authorized for the TÜİK SDMX service and should follow the provider’s terms and applicable attribution requirements for retrieved data. tuiksdmx is an independent client; no TÜİK endorsement is claimed.

The official SDMX Web Service Documentation describes API-key authentication and Bearer-token access. The TÜİK Legal Notice addresses reuse and attribution of TÜİK content. Users must comply with applicable provider terms, including any API-key agreements; the general legal notice does not imply unrestricted API access or override those agreements.

The package supports three ways to provide an API key:

An explicit api_key takes precedence over the environment variable. It is also supported by authenticated discovery, exploration, profiles and metadata operations. The object named api above is a placeholder for a key obtained securely; do not store it in tracked scripts or print credentials or tokens.

Download safeguards and performance

Response times can vary considerably. Selected development requests took approximately one second on some attempts and over a minute on others; the cause was not confirmed. A short period or allow_all = TRUE does not guarantee a small response.

Guides

The README is a starting point, not a complete function reference. Six guides are included in the package and available on the documentation website:

After installation, use browseVignettes("tuiksdmx") to view built guides in R. For individual function arguments and examples, open R help pages such as ?tuik_get_data, ?tuik_search_dataflows, and ?tuik_decode_data.

Labels and readable outputs: tuik_get_data(..., labels = "tr") can add Turkish code descriptions; labels = "en" or "both" are also supported. The label_dimensions argument controls which dimensions are decoded. See the Labels and decoding guide for a worked example.

The pkgdown documentation website brings together the function reference, all six guides and the changelog.

Scope and limitations

tuiksdmx is a focused SDMX client. It is not intended to duplicate broader TÜİK portal resource discovery, Excel downloads or geographic functionality provided by other tooling such as tuikr.

The package does not claim support for server-side partial/wildcard SDMX keys, ContentConstraint querying, streaming, or guaranteed hard limits on downloads. Selected CPI and birth Dataflows were used during development; success with these does not establish compatibility with every Dataflow or future service configuration.

Development and quality

The project has a testthat suite and an automated R CMD check workflow covering R release on Ubuntu, Windows and macOS, plus R-devel on Linux. Before the 0.1.1 version update, pre-submission CI validation passed 559 test expectations; the Linux R-devel R CMD check --as-cran result was 0 errors, 0 warnings, and 1 note (“New submission”), including a successful indexed PDF manual check. These are offline package checks, not a guarantee of live API availability.

Contributions and reproducible bug reports can be shared through GitHub Issues. Do not attach credentials, tokens or private session files.

License

tuiksdmx is distributed under the MIT License. This license applies to the package code, not to TÜİK datasets.