Get started with aradR

aradR is an independent R client for the public Czech National Bank ARAD API. It is designed around a simple workflow:

1. configure an ARAD API key;
2. find a series using human-readable metadata;
3. inspect the candidate before downloading observations;
4. retrieve a bounded window or the full available history;
5. reshape the result when a wide analytical table is more convenient;
6. retain diagnostics when reproducibility matters.

aradR is a personal open-source project authored and maintained by Simona Malovana. It is not official Czech National Bank software.

Install

For the released package on CRAN:

install.packages("aradR")

For the current development version:

pak::pak("simonamalovana/aradR")
# alternatively: remotes::install_github("simonamalovana/aradR")

Configure the API key

ARAD API access requires a key associated with an ARAD user account. Generate the key in ARAD and store it outside source code. A convenient place is ~/.Renviron:

ARAD_API_KEY=your_key_here

Restart R after editing .Renviron. Never commit the key to a repository, notebook, vignette, screenshot, or example output.

aradR 0.2.0 targets the public ARAD API only. Organization-internal endpoints and integrated authentication are intentionally outside this package.

Find a series

ARAD metadata endpoints are scoped. Start from a known set, base, selection, or indicator ID. Within that scope, aradR removes the need to know individual series IDs in advance.

library(aradR)

hits <- arad_find(
  "inflation",
  set_id = 1058,
  lang = "en"
)

hits[, c("indicator_id", "indicator_name", "relevance_score", "matched_in")]

arad_find() searches indicator names and IDs, hierarchy paths and, by default, dimension metadata. Results are ranked deterministically, and matched_in explains which metadata fields produced the match.

For browsing rather than searching, build a catalogue:

catalog <- arad_catalog(set_id = 1058, lang = "en")

For a lightweight name/ID search, use arad_search():

quick_hits <- arad_search("inflation", set_id = 1058, lang = "en")

See the Finding data article for a fuller discovery workflow.

Inspect a candidate

Before downloading observations, inspect the selected series:

info <- arad_info(hits$indicator_id[1], lang = "en")

info$summary
info$dimensions
info$updates

The summary combines basic metadata, hierarchy path and ARAD-reported availability. data_from and data_to are availability boundaries; data_to can extend into a forecast or reporting horizon and should not automatically be interpreted as the latest observed historical date.

Retrieve data

For a reproducible analytical window, specify dates explicitly:

x <- arad_get(
  indicator_ids = hits$indicator_id[1],
  from = "2020-01-01",
  to = "2026-01-01"
)

For the full ARAD-reported history, omit the date boundaries:

x <- arad_get(indicator_ids = hits$indicator_id[1])

aradR resolves missing boundaries through /updates and divides long histories into bounded requests. The returned data are long-format tibbles with indicator_id, snapshot_id, period, and value. Genuine missing source values remain NA.

Reshape to a wide table

wide <- arad_wide(x)
wide

arad_wide() keeps one row per period. If the same indicator is present in several snapshot contexts, snapshot IDs are added to the series names automatically so observations are not conflated.

Work with snapshots

List available snapshots with:

snaps <- arad_snapshots(lang = "en")

Then request a specific snapshot or an ARAD snapshot selector through snapshot_ids:

snapshot_data <- arad_get(
  indicator_ids = "MBOPCAHDPPECY",
  snapshot_ids = "LAST"
)

Use caching only when you want it

Caching is off by default. Enable it explicitly when repeated calls should reuse raw responses:

x <- arad_get("SMV5M603", cache = "session")

x <- arad_get(
  "SMV5M603",
  cache = "disk",
  cache_max_age = 24 * 60 * 60
)

Clear package caches with:

arad_cache_clear()

Disk caching uses R’s user cache directory. API keys are not stored in cached response files.

Keep retrieval diagnostics

Every arad_get() result carries retrieval diagnostics:

attr(x, "arad_diagnostics")

The diagnostics report the retrieval strategy, resolved range, number of data requests and chunk size used. arad_wide() preserves this attribute.

For analytical work, record the indicator IDs, requested date range, snapshot choice if relevant, package version and retrieval diagnostics. When presenting ARAD data, cite the underlying data source as Czech National Bank ARAD; package citation and data-source citation are separate.

For details on chunking, parsing, missing values and error handling, continue with the Reliability and reproducibility article.