Package {tuiksdmx}

Build a credential-specific metadata cache key

Description

Build a credential-specific metadata cache key

Usage

.tuik_metadata_cache_key(agency, id, version, api_key = NULL)

Arguments

Value

A credential-specific cache key.

Parse a TÜİK SDMX Codelist node

Description

Parse a TÜİK SDMX Codelist node

Usage

.tuik_parse_codelist_node(codelist_node)

Arguments

Value

A tibble with code, Turkish label and English label.

Parse a TÜİK SDMX ConceptScheme node

Description

Parse a TÜİK SDMX ConceptScheme node

Usage

.tuik_parse_concept_scheme_node(concept_scheme_node)

Arguments

Value

A tibble with one row per Concept.

Parse an SDMX-CSV 2.0 response

Description

Reads all columns as character to preserve SDMX codes with leading zeros. OBS_VALUE can optionally be converted to numeric when every non-blank value is safely convertible.

Usage

.tuik_parse_sdmx_csv_response(resp, parse_observation = TRUE)

Arguments

Value

A tibble.

Extract attributes from a TÜİK SDMX DSD

Description

Parses attribute components and their coded representations from a DSD.

Usage

tuik_attributes(dsd)

Arguments

Value

A tibble describing DSD attributes.

Retrieve codes observed in a Dataflow for a time window

Description

Returns values of a dimension that are actually present in data returned by the selected Dataflow over a bounded period. This is intentionally distinct from tuik_dimension_codes(), which returns the theoretical Codelist domain.

Usage

tuik_available_codes(
  profile,
  dimension,
  start_period,
  end_period,
  filters = NULL,
  labels = TRUE,
  api_key = NULL,
  query_mode = c("auto", "all"),
  allow_all = FALSE
)

Arguments

Details

By default query_mode = "auto" uses a server-side key for complete filters. Partial or absent filters require the explicit allow_all = TRUE opt-in because the service may return a large all response. query_mode = "all" also requires allow_all = TRUE. Both period bounds are required. Period bounds do not impose a limit on response size or memory usage. This is observed data availability, not an SDMX ContentConstraint.

Value

A tibble with observed code values, row counts and optional labels.

Examples

## Not run: 
tuik_available_codes(
  profile,
  dimension = "COICOP_2018",
  start_period = "2026-01",
  end_period = "2026-03",
  allow_all = TRUE  # No filters: explicit broad-download opt-in
)

tuik_available_codes(
  profile,
  dimension = "COICOP_2018",
  start_period = "2026-01",
  end_period = "2026-03",
  filters = list(FREQ = "M", REF_AREA = "TR"),
  allow_all = TRUE  # Partial filters: downloaded data are filtered locally
)

## End(Not run)

Build an SDMX data key

Description

Builds a series key using the exact dimension order defined by the DSD.

Usage

tuik_build_key(profile, filters)

Arguments

Details

Each dimension may contain:

• one value, e.g. "M"

• multiple values, e.g. c("01", "02")

Multiple values are joined using the SDMX "+" separator.

At the current stage, all series dimensions must be supplied explicitly. This is intentional because blank-segment wildcard behaviour has not been reliably confirmed for the TÜİK service.

Value

Character string containing the SDMX key.

Examples

## Not run: 
# Requires TUIK_SDMX_API_KEY in the environment.
library(tuiksdmx)
profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")

key <- tuik_build_key(
  profile,
  filters = list(
    REF_AREA = "TR",
    FREQ = "M",
    SINIFLAMA_DUZEYI = "2",
    DEGISIM = "1",
    OZEL_KAPSAM_TUFE = "_Z",
    BASE_PER = "2025",
    YAYIM_DONEMI = "2026_01",
    COICOP_1999 = "_Z",
    COICOP_2018 = c("01", "02"),
    INDICATOR = "F_TFE"
  )
)

## End(Not run)

Build a TUIK SDMX request

Description

Creates an authenticated HTTP request for a TUIK SDMX REST endpoint.

Usage

tuik_build_request(path, query = list(), accept = NULL, api_key = NULL)

Arguments

Value

An httr2 request object.

Get a cached TUIK SDMX access token

Description

Returns the access token associated with the selected API key. If no token is cached, requests a new one.

Usage

tuik_cached_token(api_key = NULL)

Arguments

Value

A character string containing the access token.

Clear cached Codelists

Description

Removes all Codelists stored in the current R session cache.

Usage

tuik_clear_codelist_cache()

Value

NULL invisibly.

Clear cached ConceptSchemes

Description

Clear cached ConceptSchemes

Usage

tuik_clear_concept_cache()

Value

NULL invisibly.

Clear the cached Dataflow catalogue

Description

Removes the in-memory Dataflow catalogue cache.

Usage

tuik_clear_dataflow_cache()

Details

This is mainly useful when the catalogue is known to have changed or during development and testing.

Value

NULL invisibly.

Clear a cached TUIK SDMX access token

Description

Removes the access token associated with the selected API key without affecting tokens belonging to other keys.

Usage

tuik_clear_token(api_key = NULL)

Arguments

Value

NULL invisibly.

Retrieve concepts used by a TÜİK Dataflow

Description

Resolves the concepts referenced by dimensions, measures and attributes in a flow profile and adds their Turkish/English labels and descriptions.

Usage

tuik_concepts(profile, refresh = FALSE, api_key = NULL)

Arguments

Value

A tibble with component-to-concept mappings and semantic metadata.

List TÜİK SDMX Dataflows

Description

Retrieves the current Dataflow catalogue published by TÜİK.

Usage

tuik_dataflows(
  agency = "TR",
  version = "latest",
  refresh = FALSE,
  api_key = NULL
)

Arguments

Details

The returned table contains:

• Dataflow agency, ID and version

• Final/non-final status

• Turkish and English names

• Referenced DSD agency, ID and version

Results are cached in memory for the current R session. Use refresh = TRUE to force a new request to the TÜİK SDMX service.

Value

A tibble with one row per Dataflow.

Examples

## Not run: 
flows <- tuik_dataflows()

# Force a fresh download
flows <- tuik_dataflows(refresh = TRUE)

## End(Not run)

Add SDMX code labels to an observation table

Description

Joins dimension code labels from the Codelists referenced by a Dataflow profile. Original SDMX dimension codes and observations are preserved. The labels describe Codelist definitions, not observed availability.

Usage

tuik_decode_data(
  data,
  profile,
  dimensions = NULL,
  language = c("tr", "en", "both"),
  api_key = NULL
)

Arguments

Value

A tibble containing the input columns plus DIMENSION_label_tr and/or DIMENSION_label_en columns. Unknown code labels remain NA.

Examples

## Not run: 
# Requires TUIK_SDMX_API_KEY in the environment.
library(tuiksdmx)
profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")

# Use the complete CPI filter set documented in tuik_get_data().
# Check current metadata before reuse; codes and availability may change.
data <- tuik_get_data(
  profile,
  filters = list(
    REF_AREA = "TR",
    FREQ = "M",
    SINIFLAMA_DUZEYI = "2",
    DEGISIM = "1",
    OZEL_KAPSAM_TUFE = "_Z",
    BASE_PER = "2025",
    YAYIM_DONEMI = "2026_01",
    COICOP_1999 = "_Z",
    COICOP_2018 = "01",
    INDICATOR = "F_TFE"
  ),
  start_period = "2026-01",
  end_period = "2026-01"
)

decoded <- tuik_decode_data(data, profile, dimensions = c("DEGISIM", "FREQ"))

## End(Not run)

Retrieve codes for a DSD dimension

Description

Finds the Codelist referenced by a dimension and returns its codes.

Usage

tuik_dimension_codes(
  dimensions,
  dimension,
  search = NULL,
  language = c("both", "tr", "en"),
  limit = 50,
  api_key = NULL
)

Arguments

Details

Optionally searches within code values and Turkish/English labels.

Value

A tibble containing the dimension codes.

Examples

## Not run: 
tuik_dimension_codes(
  dimensions,
  "FREQ"
)

tuik_dimension_codes(
  dimensions,
  "COICOP_2018",
  search = "food"
)

## End(Not run)

Extract dimensions from a TÜİK SDMX DSD

Description

Parses Dimension and TimeDimension components from a DSD.

Usage

tuik_dimensions(dsd)

Arguments

Value

A tibble describing DSD dimensions.

Explore a TUIK SDMX Dataflow before downloading observations

Description

Displays structural components from a Dataflow's DSD without downloading observations. Series dimensions are selected using filters; TIME_PERIOD uses start_period and end_period in tuik_get_data(). A specific coded dimension can be inspected on demand. Codelist entries are theoretical, not necessarily observed in a selected time window.

Usage

tuik_explore(
  dataflow,
  dimension = NULL,
  search = NULL,
  language = c("both", "tr", "en"),
  limit = 50,
  api_key = NULL,
  filters = NULL
)

Arguments

Value

Without dimension, a tibble describing DSD components and how to select them. If filters is supplied, also shows selections and missing series dimensions. With dimension, a tibble of Codelist codes and labels.

Examples

## Not run: 
tuik_explore("DF_TUFE_SDMX_TT01")
tuik_explore("DF_TUFE_SDMX_TT01", dimension = "DEGISIM")
selections <- list(REF_AREA = "TR", FREQ = "M", DEGISIM = "1")
tuik_explore("DF_TUFE_SDMX_TT01", filters = selections)
data <- tuik_get_data("DF_TUFE_SDMX_TT01", filters = selections,
                      filter_mode = "local", start_period = "2026-01",
                      end_period = "2026-01")

## End(Not run)

Show required filters for a TÜİK SDMX Dataflow

Description

Returns the dimensions required to build a series key together with their referenced Codelists.

Usage

tuik_filter_dimensions(profile)

Arguments

Value

A tibble describing required filter dimensions.

Create a filter template for a TÜİK SDMX Dataflow

Description

Creates a named list containing all dimensions required for an SDMX series key. Each value is initially NULL and can be filled by the user.

Usage

tuik_filter_template(profile)

Arguments

Details

TIME_PERIOD is excluded because time filtering is handled separately through startPeriod and endPeriod.

Value

A named list with one element per series-key dimension.

Examples

## Not run: 
# Requires TUIK_SDMX_API_KEY in the environment.
library(tuiksdmx)
profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")

filters <- tuik_filter_template(profile)

filters$REF_AREA <- "TR"
filters$FREQ <- "M"

## End(Not run)

Build a profile for a TÜİK SDMX Dataflow

Description

Retrieves a Dataflow, follows its referenced DSD and parses its structural components.

Usage

tuik_flow_profile(
  dataflow_id,
  agency = "TR",
  version = "latest",
  api_key = NULL
)

Arguments

Value

A list with the following components:

• dataflow

• dsd

• dimensions

• measures

• attributes

Examples

## Not run: 
profile <- tuik_flow_profile(
  "DF_TUFE_SDMX_TT01",
  version = "1.0"
)

profile$dimensions

## End(Not run)

Get a new TUIK SDMX access token

Description

Requests an access token from the TUIK authentication service.

Usage

tuik_get_access_token(api_key = NULL)

Arguments

Value

An access-token character string. When the server supplies a positive numeric expires_in, it is attached as an internal attribute.

Retrieve a TÜİK SDMX Codelist

Description

Downloads and parses an SDMX Codelist.

Usage

tuik_get_codelist(
  codelist_id,
  agency,
  version = "latest",
  refresh = FALSE,
  api_key = NULL
)

Arguments

Details

Results are cached in memory for the current R session.

Value

A tibble with code, Turkish label and English label.

Retrieve a TÜİK SDMX ConceptScheme

Description

Downloads and parses a ConceptScheme. Results are cached in memory for the current R session.

Usage

tuik_get_concept_scheme(
  concept_scheme_id,
  agency,
  version = "latest",
  refresh = FALSE,
  api_key = NULL
)

Arguments

Value

A tibble with Concept IDs and multilingual labels/descriptions.

Retrieve data from a TÜİK SDMX Dataflow

Description

Retrieves all series with filters = NULL, or builds a complete SDMX key from supplied filters. Partial filters require explicit permission via allow_all = TRUE or filter_mode = "local": the service's all data are retrieved first and filters are applied in R. At least one period bound is required unless allow_unbounded = TRUE. This is NOT server-side filtering and can download large responses even for a short period. Complete filters are always queried by SDMX key on the server.

Usage

tuik_get_data(
  profile,
  filters = NULL,
  start_period = NULL,
  end_period = NULL,
  parse_observation = TRUE,
  validate = TRUE,
  api_key = NULL,
  allow_unbounded = FALSE,
  labels = c("none", "tr", "en", "both"),
  label_dimensions = NULL,
  filter_mode = c("reject", "local"),
  allow_all = FALSE
)

Arguments

Value

A tibble containing SDMX observations. If labels are requested, additional ⁠<DIMENSION>_label_tr⁠ and/or ⁠<DIMENSION>_label_en⁠ columns are appended. Labels identify Codelist-defined values, not observed availability.

Examples

## Not run: 
# Requires TUIK_SDMX_API_KEY in the environment.
library(tuiksdmx)
profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01")

data <- tuik_get_data(
  profile,
  filters = list(
    REF_AREA = "TR",
    FREQ = "M",
    SINIFLAMA_DUZEYI = "2",
    DEGISIM = "1",
    OZEL_KAPSAM_TUFE = "_Z",
    BASE_PER = "2025",
    YAYIM_DONEMI = "2026_01",
    COICOP_1999 = "_Z",
    COICOP_2018 = "01",
    INDICATOR = "F_TFE"
  ),
  start_period = "2026-01",
  end_period = "2026-03"
)

## End(Not run)

Retrieve a single TÜİK SDMX Dataflow

Description

Retrieves metadata for one Dataflow and its referenced DSD.

Usage

tuik_get_dataflow(
  dataflow_id,
  agency = "TR",
  version = "latest",
  api_key = NULL
)

Arguments

Value

A one-row tibble.

Examples

## Not run: 
tuik_get_dataflow(
  "DF_TUFE_SDMX_TT01",
  version = "1.0"
)

## End(Not run)

Retrieve a TÜİK SDMX Data Structure Definition

Description

Retrieves a DSD from the TÜİK SDMX Web Service.

Usage

tuik_get_dsd(dsd_id, agency = "TR", version = "latest", api_key = NULL)

Arguments

Value

An xml2 XML document.

Examples

## Not run: 
dsd <- tuik_get_dsd(
  "DSD_TUFE",
  version = "1.12"
)

## End(Not run)

Return the dimensions used in an SDMX series key

Description

Extracts ordinary series dimensions from a TÜİK flow profile.

Usage

tuik_key_dimensions(profile)

Arguments

Details

TimeDimension components such as TIME_PERIOD are excluded because they are supplied separately through time query parameters.

Value

A tibble containing the key dimensions in DSD order.

Extract measures from a TÜİK SDMX DSD

Description

Parses measure components from a DSD.

Usage

tuik_measures(dsd)

Arguments

Value

A tibble describing DSD measures.

Identify missing SDMX key filters

Description

Compares a filter list with the dimensions required by the DSD.

Usage

tuik_missing_filters(profile, filters)

Arguments

Value

Character vector containing missing dimension IDs.

Normalise text for searching

Description

Converts text to lower case, replaces Turkish-specific characters with ASCII equivalents and normalises whitespace.

Usage

tuik_normalize_text(x)

Arguments

Details

Examples: "Tuketici Fiyat" -> "tuketici fiyat" "ISGUCU" -> "isgucu"

Value

A normalised character vector.

Perform a TUIK SDMX request

Description

Performs an authenticated request against the TUIK SDMX REST service.

Usage

tuik_perform(
  path,
  query = list(),
  accept = NULL,
  timeout = 60,
  max_tries = 3,
  api_key = NULL
)

Arguments

Details

Behaviour:

• Uses an explicitly supplied or environment-based API key

• Retrieves the token associated with that API key

• Retries temporary connection failures

• Refreshes only the selected credential's token on HTTP 401

• Retries the request once after token refresh

• Converts remaining HTTP errors into readable R errors

Value

An httr2 response object.

Preload Codelists used by a Dataflow

Description

Retrieves descendant structures for a Dataflow and stores all returned Codelists in the in-memory Codelist cache.

Usage

tuik_preload_codelists(profile, refresh = FALSE, api_key = NULL)

Arguments

Details

This is more efficient than downloading each Codelist separately when several dimensions need to be validated.

Value

The number of Codelists stored in the cache, invisibly.

Preload ConceptSchemes used by a Dataflow

Description

Retrieves descendant structures for a Dataflow and stores all returned ConceptSchemes in the in-memory ConceptScheme cache.

Usage

tuik_preload_concepts(profile, refresh = FALSE, api_key = NULL)

Arguments

Value

The number of ConceptSchemes stored in the cache, invisibly.

Perform a TUIK SDMX request without stopping on HTTP errors

Description

Intended mainly for diagnostics, tests and endpoint exploration.

Usage

tuik_probe(path, query = list(), accept = NULL, timeout = 60, api_key = NULL)

Arguments

Details

Unlike tuik_perform(), HTTP 4xx and 5xx responses are returned instead of converted into R errors.

A single token refresh is attempted after HTTP 401.

Value

An httr2 response object.

Refresh a cached TUIK SDMX access token

Description

Requests a new access token and updates only the cache entry corresponding to the selected API key.

Usage

tuik_refresh_token(api_key = NULL)

Arguments

Details

If authentication fails, the existing cache entry remains unchanged.

Value

The new access token invisibly.

Resolve a TUIK SDMX API key

Description

Uses an explicitly supplied API key or, when NULL, the TUIK_SDMX_API_KEY environment variable.

Usage

tuik_resolve_api_key(api_key = NULL)

Arguments

Value

A non-empty character string.

Search concepts used by a TÜİK Dataflow

Description

Searches component IDs, concept IDs, labels and descriptions in the concepts referenced by a flow profile.

Usage

tuik_search_concepts(
  profile,
  query,
  language = c("both", "tr", "en"),
  limit = 50,
  api_key = NULL
)

Arguments

Value

A filtered concept tibble.

Search TÜİK SDMX Dataflows

Description

Searches the TÜİK SDMX Dataflow catalogue using a keyword or phrase.

Usage

tuik_search_dataflows(
  query,
  language = c("both", "tr", "en"),
  final_only = FALSE,
  limit = 25,
  fuzzy = TRUE,
  refresh = FALSE,
  dataflows = NULL,
  api_key = NULL
)

Arguments

Details

Search fields:

• Dataflow ID

• Turkish Dataflow name

• English Dataflow name

• Referenced DSD ID

Search is case-insensitive and tolerant of Turkish characters.

For example:

"tüketici fiyat" "tuketici fiyat"

are treated equivalently.

If no exact substring match is found, an optional conservative fallback search is performed using shortened word variants. This may help with expressions such as "işsizlik" when catalogue labels contain "işsiz".

Value

A tibble containing matching Dataflows.

Examples

## Not run: 
tuik_search_dataflows("tüketici fiyat")

tuik_search_dataflows("tuketici fiyat")

tuik_search_dataflows("işsizlik")

tuik_search_dataflows(
  "consumer price",
  language = "en"
)

## End(Not run)

Create fallback search variants

Description

Generates progressively shorter variants of a search term.

Usage

tuik_search_variants(x, max_trim = 3)

Arguments

Details

This is used only when an exact substring search returns no results. It provides a lightweight fallback for cases such as:

"issizlik" -> "issiz"

It is deliberately conservative and is not intended to be a linguistic stemmer.

Value

Character vector of candidate search strings.

Create a token cache identifier

Description

Creates a SHA-256 identifier from an API key. The raw API key is not used as a cache name.

Usage

tuik_token_cache_id(api_key)

Arguments

Value

A SHA-256 hexadecimal character string.

Validate SDMX filter values against referenced Codelists

Description

Checks whether supplied filter values exist in the Codelists referenced by the Dataflow's DSD.

Usage

tuik_validate_filters(profile, filters, stop_on_error = TRUE, api_key = NULL)

Arguments

Value

A tibble with one row per supplied filter value.