## ----setup, include=FALSE-----------------------------------------------------
# All examples require a live authenticated TÜİK service. They are deliberately
# not executed during vignette building or R CMD check.
knitr::opts_chunk$set(eval = FALSE, collapse = TRUE, comment = "#>")

## ----install------------------------------------------------------------------
# # Option A: pak
# install.packages("pak")  # if needed
# pak::pak("MFatihTuzen/tuiksdmx")
# 
# # Option B: remotes
# install.packages("remotes")  # if needed
# remotes::install_github("MFatihTuzen/tuiksdmx")

## ----explicit-key-------------------------------------------------------------
# # Assume `api` contains a securely obtained key; do not hard-code it.
# profile <- tuik_flow_profile("DF_TUFE_SDMX_TT01", api_key = api)
# raw <- tuik_get_data(profile, start_period = "2026-01",
#                      end_period = "2026-01", api_key = api)

## ----session-env--------------------------------------------------------------
# Sys.setenv(TUIK_SDMX_API_KEY = api)
# # Authenticated calls can now omit api_key for the current R session.

## ----load---------------------------------------------------------------------
# library(tuiksdmx)

## ----catalogue----------------------------------------------------------------
# # Browse the current catalogue
# flows <- tuik_dataflows()
# head(flows)

## ----search-------------------------------------------------------------------
# # Search by a Turkish expression (accent-insensitive search is supported)
# results <- tuik_search_dataflows("tüketici fiyat", limit = 10)
# results
# 
# # Or search in English
# tuik_search_dataflows("consumer price", language = "en", limit = 10)

## ----profile------------------------------------------------------------------
# id <- "DF_TUFE_SDMX_TT01"
# profile <- tuik_flow_profile(id)

## ----explore------------------------------------------------------------------
# tuik_explore(profile)

## ----inspect-dimensions-------------------------------------------------------
# tuik_filter_dimensions(profile)

## ----codes--------------------------------------------------------------------
# tuik_explore(profile, dimension = "DEGISIM")
# 
# tuik_explore(
#   profile,
#   dimension = "COICOP_2018",
#   search = "gıda"
# )

## ----download-all-------------------------------------------------------------
# raw <- tuik_get_data(
#   id,
#   start_period = "2026-01",
#   end_period = "2026-01"
# )
# 
# dim(raw)
# head(raw)

## ----unbounded----------------------------------------------------------------
# # Potentially broad and expensive; do not run casually.
# # entire_dataflow <- tuik_get_data(id, allow_unbounded = TRUE)

## ----labour-market-example----------------------------------------------------
# labour_profile <- tuik_flow_profile("DF_ISGUCU_AYLIK_TEMEL_ISGUCU_C")
# 
# unemployment_sa <- tuik_get_data(
#   labour_profile,
#   filters = list(
#     REF_AREA = "TR",
#     FREQ = "M",
#     INDICATOR = "ISGI_TIG",
#     ISGUCU_GOSTERGE = "8",
#     TEMEL_YAS = "Y_GE15",
#     SEASONAL_ADJUST = "S",
#     SEX = "_T",
#     FIIL_CALISMA_SURE = "_Z",
#     YAYIM_DONEMI = "2026_01"
#   ),
#   start_period = "2026-01",
#   end_period = "2026-01"
# )
# 
# unemployment_sa[, c("TIME_PERIOD", "OBS_VALUE"), drop = FALSE]

## ----partial------------------------------------------------------------------
# chosen <- list(
#   REF_AREA = "TR",
#   FREQ = "M",
#   DEGISIM = "1",
#   SINIFLAMA_DUZEYI = "2"
# )
# 
# # Inspect selected and missing key dimensions; this is structural only.
# tuik_explore(profile, filters = chosen)
# 
# selected <- tuik_get_data(
#   profile,
#   filters = chosen,
#   start_period = "2026-01",
#   end_period = "2026-01",
#   allow_all = TRUE,
#   labels = "tr"
# )
# 
# head(selected)

## ----full-key-----------------------------------------------------------------
# full_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"
# )
# 
# # Full key in the order prescribed by the DSD
# tuik_build_key(profile, full_filters)
# 
# food_index <- tuik_get_data(
#   profile,
#   filters = full_filters,
#   start_period = "2026-01",
#   end_period = "2026-03",
#   labels = "both"
# )
# 
# head(food_index)

## ----observed-----------------------------------------------------------------
# # Theoretical domain: all defined codes for the dimension
# defined <- tuik_dimension_codes(
#   profile,
#   dimension = "COICOP_2018"
# )
# 
# # Observed domain: codes actually present in data for a specific query
# observed <- tuik_available_codes(
#   profile,
#   dimension = "COICOP_2018",
#   filters = chosen,
#   start_period = "2026-01",
#   end_period = "2026-01",
#   allow_all = TRUE
# )
# 
# head(defined)
# observed