Package 'cnbrrr'

Retrieve data from ARAD API

Description

This function retrieves data from the Czech National Bank's ARAD API for specified indicators. Data can be retrieved by indicator IDs, set ID, base ID, or selection ID, with optional date filtering and value column renaming.

Usage

arad_get_data(
  indicator_ids = NULL,
  set_id = NULL,
  base_id = NULL,
  selection_id = NULL,
  period_from = NULL,
  period_to = NULL,
  months_before = NULL,
  rename_value = NULL,
  api_key = NULL,
  base_url = "https://www.cnb.cz/aradb/api/v1",
  process_data = TRUE,
  encoding = "windows-1250",
  dest_dir = NULL,
  force_redownload = FALSE
)

Arguments

indicator_ids	Character vector of indicator IDs to retrieve (primary method)
set_id	Character, set ID to retrieve data from a specific data set
base_id	Character, base ID to retrieve data for specific base indicators
selection_id	Character, ID of a named selection created in ARAD user account
period_from	Character, start date in YYYYMMDD format (e.g., "20200101")
period_to	Character, end date in YYYYMMDD format (e.g., "20231231")
months_before	Integer, number of months before current date to retrieve data for
rename_value	Character, new name for the 'value' column in the output
api_key	API key for ARAD access. If NULL, uses ARAD_API_KEY environment variable
base_url	Base URL for the ARAD API
process_data	Logical, whether to process the raw data (default TRUE)
encoding	Character encoding for the response (default "windows-1250")
dest_dir	Character, directory where downloaded files are saved. Defaults to getOption("cnbrrr.dest_dir", tempdir())
force_redownload	Logical, if TRUE forces redownload even if file exists (default FALSE)

Value

A data frame with the requested data

Examples

## Not run: 
# Get data for a single indicator
data <- arad_get_data("SRUMD08402C")

# Get data for multiple indicators
data <- arad_get_data(c("SRUMD08402C", "ANOTHER_ID"))

# Get data with date filtering
data <- arad_get_data("SRUMD08402C",
                      period_from = "20200101",
                      period_to = "20231231")

# Get data from a set ID
data <- arad_get_data(set_id = "1115")

# Get data from a selection with custom value column name
data <- arad_get_data(selection_id = "my_selection",
                      rename_value = "spending")

# Get recent data using months_before
recent_data <- arad_get_data("SRUMD08402C", months_before = 12)

# Save data to specific directory
data <- arad_get_data("SRUMD08402C", dest_dir = "./data")

# Force redownload of existing data
fresh_data <- arad_get_data("SRUMD08402C", force_redownload = TRUE)

# Set global destination directory
options(cnbrrr.dest_dir = "~/cnb_data")
data <- arad_get_data("SRUMD08402C")  # Will use ~/cnb_data

## End(Not run)

---

Get indicator dimensions from ARAD API

Description

This function retrieves the dimensional structure of indicators from the ARAD API, showing how indicators are organized and what dimensions are available.

Usage

arad_indicators_dims(
  set_id = NULL,
  indicator_id_list = NULL,
  selection_id = NULL,
  api_key = NULL,
  base_url = "https://www.cnb.cz/aradb/api/v1",
  encoding = "windows-1250"
)

Arguments

set_id	Character, set ID to get dimensions for a specific data set (required unless indicator_id_list or selection_id is provided)
indicator_id_list	Character vector, specific indicator IDs to retrieve dimensions for (required unless set_id or selection_id is provided). Will be converted to comma-separated string.
selection_id	Character, ID of a named selection created in ARAD user account (required unless set_id or indicator_id_list is provided)
api_key	API key for ARAD access. If NULL, uses ARAD_API_KEY environment variable
base_url	Base URL for the ARAD API
encoding	Character encoding for the response (default "windows-1250")

Value

A data frame with indicator dimensions

Examples

## Not run: 
# Get all indicator dimensions
dimensions <- arad_indicators_dims()

# Get dimensions for a specific data set
monetary_dims <- arad_indicators_dims(set_id = "MONETARY_SET")

# Get dimensions for specific indicators
specific_dims <- arad_indicators_dims(indicator_id_list = "SRUMD08402")
multiple_dims <- arad_indicators_dims(indicator_id_list = c("SRUMD08402", "SRUMD08403"))

# Get dimensions from a named selection
selection_dims <- arad_indicators_dims(selection_id = "my_selection")

## End(Not run)

---

Get indicator tree structure from ARAD API

Description

This function retrieves the hierarchical tree structure of indicators from the ARAD API, showing how indicators are organized in a tree format with categories and subcategories.

Usage

arad_indicators_tree(
  set_id = NULL,
  indicator_id_list = NULL,
  selection_id = NULL,
  api_key = NULL,
  base_url = "https://www.cnb.cz/aradb/api/v1",
  encoding = "windows-1250"
)

Arguments

set_id	Character, set ID to get tree structure for a specific data set (required unless indicator_id_list or selection_id is provided)
indicator_id_list	Character vector, specific indicator IDs to retrieve tree structure for (required unless set_id or selection_id is provided). Will be converted to comma-separated string.
selection_id	Character, ID of a named selection created in ARAD user account (required unless set_id or indicator_id_list is provided)
api_key	API key for ARAD access. If NULL, uses ARAD_API_KEY environment variable
base_url	Base URL for the ARAD API
encoding	Character encoding for the response (default "windows-1250")

Value

A data frame with the hierarchical indicator tree structure

Examples

## Not run: 
# Get full indicator tree
tree <- arad_indicators_tree()

# Get tree structure for a specific data set
monetary_tree <- arad_indicators_tree(set_id = "MONETARY_SET")

# Get tree structure for specific indicators
specific_tree <- arad_indicators_tree(indicator_id_list = "SRUMD08402")
multiple_tree <- arad_indicators_tree(indicator_id_list = c("SRUMD08402", "SRUMD08403"))

# Get tree structure from a named selection
selection_tree <- arad_indicators_tree(selection_id = "my_selection")

## End(Not run)

---

List available indicators from ARAD API

Description

This function retrieves the list of available indicators from the ARAD API. You can filter the results by providing a search term that will match indicator names (case-insensitive).

Usage

arad_list_indicators(
  set_id = NULL,
  base_id = NULL,
  indicator_id_list = NULL,
  selection_id = NULL,
  filter = NULL,
  api_key = NULL,
  base_url = "https://www.cnb.cz/aradb/api/v1",
  encoding = "windows-1250"
)

arad_get_indicators(
  set_id = NULL,
  base_id = NULL,
  indicator_id_list = NULL,
  selection_id = NULL,
  filter = NULL,
  api_key = NULL,
  base_url = "https://www.cnb.cz/aradb/api/v1",
  encoding = "windows-1250"
)

Arguments

set_id	Character, set ID to filter indicators from a specific data set (required unless base_id, indicator_id_list, or selection_id is provided)
base_id	Character, base ID to filter specific indicators (required unless set_id, indicator_id_list, or selection_id is provided)
indicator_id_list	Character vector, specific indicator IDs to retrieve (required unless set_id, base_id, or selection_id is provided). Will be converted to comma-separated string.
selection_id	Character, ID of a named selection created in ARAD user account (required unless set_id, base_id, or indicator_id_list is provided)
filter	Character, optional search term to filter indicator names (case-insensitive)
api_key	API key for ARAD access. If NULL, uses ARAD_API_KEY environment variable
base_url	Base URL for the ARAD API
encoding	Character encoding for the response (default "windows-1250")

Details

To use this function effectively, you need to understand ARAD's structure:

• set_id: Identifies a data set (collection of related indicators)

• base_id: Identifies the base indicator within a set

• Find these IDs by browsing the ARAD web interface at https://www.cnb.cz/arad/

Value

A data frame with available indicators and their metadata

Examples

## Not run: 
# Get all available indicators
indicators <- arad_list_indicators()

# Filter indicators by name (case-insensitive)
gdp_indicators <- arad_list_indicators(filter = "GDP")

# Get indicators from a specific data set
monetary_indicators <- arad_list_indicators(set_id = "MONETARY_SET")

# Get specific indicator by base_id (base part without suffix)
specific_indicator <- arad_list_indicators(base_id = "SRUMD084")

# Get specific indicators by indicator IDs
specific_indicators <- arad_list_indicators(indicator_id_list = "SRUMD08402")
multiple_indicators <- arad_list_indicators(indicator_id_list = c("SRUMD08402", "SRUMD08403"))

# Get indicators from a named selection
selection_indicators <- arad_list_indicators(selection_id = "my_selection")

## End(Not run)

---

Convert ARAD period to Date

Description

Helper function to convert ARAD period format (YYYYMMDD) to Date object

Usage

arad_parse_date(period_string)

Arguments

period_string

Character vector of period strings

Value

Date vector

Examples

## Not run: 
periods <- c("20231201", "20231101")
dates <- arad_parse_date(periods)

## End(Not run)

---

Validate indicator IDs

Description

Helper function to validate ARAD indicator ID format

Usage

arad_validate_indicators(indicator_ids)

Arguments

indicator_ids

Character vector of indicator IDs

Value

Logical vector indicating valid IDs

---