boj_cache: Refresh or manage Bank of Japan metadata caches

In bojapi: Access the Bank of Japan Time-Series Data API

Refresh or manage Bank of Japan metadata caches

Description

boj_cache() is the counterpart to WDI::WDIcache(): it retrieves current BOJ metadata and saves it to the local cache used by boj_search(). When db = NULL, all databases in boj_databases() are refreshed. This takes about one minute with the default one-second interval.

Usage

boj_cache(
  db = NULL,
  lang = boj_default("lang", "en"),
  refresh = TRUE,
  max_age = 24 * 60 * 60,
  cache_dir = boj_default("cache_dir", tools::R_user_dir("bojapi", "cache")),
  include_groups = TRUE,
  wait = boj_default("wait", 1),
  timeout = boj_default("timeout", 30),
  retries = boj_default("retries", 3),
  action = "refresh"
)

Arguments

db	Character vector of database identifiers, or NULL for all known databases when refreshing. For cache management, NULL means all bojapi metadata cache entries.
lang	Response language, "en" or "jp". Japanese responses also contain some English fields, but this function consistently returns the requested language in name, unit, category, and notes.
refresh	Ignore current cache entries and download fresh metadata. Used only when action = "refresh".
max_age	Maximum cache age in seconds; default 86,400 (24 hours).
cache_dir	Metadata cache directory.
include_groups	Include hierarchy-heading rows whose series_code is blank. These rows are useful when constructing boj_layer() queries.
wait	Requested seconds between automatic requests. The default is one second, and values below one are treated as one whenever another request is needed, to avoid high-frequency access prohibited by the BOJ.
timeout	Request timeout in seconds.
retries	Number of retries for network and transient server errors.
action	Cache operation: "refresh" preserves the existing behavior, "clear" removes matching entries, and "prune" removes matching entries that are expired, unreadable, or do not contain the expected metadata columns.

Details

Set action = "clear" to remove matching cache entries, or action = "prune" to remove only expired or invalid entries. For these management actions, db = NULL targets all bojapi metadata cache files in cache_dir, including both languages. Supplying db limits the operation to those databases and the selected lang. Other files and directories are never recursively removed.

Value

For action = "refresh", a combined metadata tibble that is also written to the per-database cache. For "clear" and "prune", a tibble reporting each matched file, path, status, and reason.

Examples

## Not run: 
current_fx_metadata <- boj_cache("FM08")
all_metadata <- boj_cache()
boj_cache(action = "prune")
boj_cache("FM08", action = "clear")

## End(Not run)

bojapi documentation built on July 24, 2026, 5:07 p.m.