Package 'bojapi'

Return the Bank of Japan API credit and release notice

Description

The BOJ asks publishers of services using its API to show a specified credit and notify its Research and Statistics Department. The terms can change without prior notice; verify the linked official notice before releasing a service.

Usage

boj_api_credit(lang = c("en", "jp"))

Arguments

lang	Credit language, "en" or "jp".

Value

A named list containing the requested credit, contact address, subject line, and official notice URL.

Examples

boj_api_credit("en")
boj_api_credit("jp")$credit

---

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)

---

Retrieve Bank of Japan time-series data by series code

Description

boj_data() is the main data function. It accepts one or more BOJ series codes, splits requests into safe batches of 250 codes, follows NEXTPOSITION until complete, and returns one observation per row. All codes in a BOJ code request must have the same frequency.

Usage

boj_data(
  db,
  code,
  start_date = NULL,
  end_date = NULL,
  lang = boj_default("lang", "en"),
  wide = FALSE,
  wait = boj_default("wait", 1),
  timeout = boj_default("timeout", 30),
  retries = boj_default("retries", 3)
)

Arguments

db	BOJ database identifier, such as "FM08".
code	Character vector of series codes without the database prefix. For example, use "MADR1Z@D", not "IR01'MADR1Z@D". Names become aliases in the series column and wide output.
start_date, end_date	Optional BOJ period codes. Accepted request forms are YYYY or YYYYPP; daily and weekly filters also use YYYYMM.
lang	Response language, "en" or "jp".
wide	If FALSE (default), return normalized long data. If TRUE, return time, parsed date, and one column per code or alias.
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.

Details

A named code vector creates convenient aliases, following the style of WDI::WDI(). The original BOJ code is always retained in series_code.

Value

A tibble. Long output contains db, series, series_code, name, unit, frequency, category, last_update, time, date, and value. time preserves the exact BOJ period code. date is the first day of non-daily periods (April 1 for fiscal years); use time when exact period semantics matter.

Examples

## Not run: 
fx <- boj_data(
  db = "FM08",
  code = c(usd_yen = "FXERM07"),
  start_date = "202401",
  end_date = "202412"
)

boj_data(
  "FM08",
  c(usd_yen = "FXERM07", euro_yen = "FXERM09"),
  start_date = "202401",
  wide = TRUE
)

## End(Not run)

---

List Bank of Japan API databases

Description

Returns the database identifiers accepted by db in the BOJ API. The registry follows the February 18, 2026 API manual. New databases may be accepted by the API before this package registry is updated.

Usage

boj_databases()

Value

A tibble with database code, English category, and English and Japanese database names.

Examples

boj_databases()
subset(boj_databases(), grepl("Exchange", name_en))

---

Retrieve Bank of Japan time-series data by hierarchy

Description

Uses the BOJ layer API to retrieve all series matching a database hierarchy and frequency. The function follows NEXTPOSITION automatically. A layer condition that identifies more than 1,250 series is rejected by the BOJ API; this count is evaluated before the frequency filter.

Usage

boj_layer(
  db,
  frequency,
  layer,
  start_date = NULL,
  end_date = NULL,
  lang = boj_default("lang", "en"),
  wide = FALSE,
  wait = boj_default("wait", 1),
  timeout = boj_default("timeout", 30),
  retries = boj_default("retries", 3)
)

Arguments

db	BOJ database identifier.
frequency	One of "CY", "FY", "CH", "FH", "Q", "M", "W", or "D".
layer	One to five hierarchy values supplied as a vector or a comma-separated string. "*" is a wildcard; for example, c(1, "*", 2).
start_date, end_date	Optional BOJ period codes. Accepted request forms are YYYY or YYYYPP; daily and weekly filters also use YYYYMM.
lang	Response language, "en" or "jp".
wide	If FALSE (default), return normalized long data. If TRUE, return time, parsed date, and one column per code or alias.
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.

Value

A long or wide tibble with the same structure as boj_data().

Examples

## Not run: 
boj_layer(
  db = "BP01", frequency = "M", layer = c(1, 1, 1),
  start_date = "202504", end_date = "202509"
)

## End(Not run)

---

Retrieve Bank of Japan series metadata

Description

Downloads the complete metadata table for one BOJ database. Metadata includes both hierarchy headings (blank series_code) and actual series. By default it is cached for 24 hours, matching the API's daily metadata update cycle and reducing load on the BOJ service.

Usage

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

Arguments

db	BOJ database identifier, such as "FM08".
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.
cache	Whether to read and write the on-disk metadata cache.
refresh	If TRUE, ignore an existing cache entry.
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.
timeout	Request timeout in seconds.
retries	Number of retries for network and transient server errors.
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.

Value

A tibble with normalized metadata. start_time and end_time preserve exact BOJ period codes. Parsed date columns indicate the first day of each period and are NA for hierarchy headings.

Examples

## Not run: 
metadata <- boj_metadata("FM08", lang = "jp")
subset(metadata, is_series)

## End(Not run)

---

Search Bank of Japan series metadata

Description

Searches current BOJ metadata in the same spirit as WDI::WDIsearch(). Supply a database to fetch/cache metadata, or pass a metadata tibble directly for an offline or reproducible search.

Usage

boj_search(
  pattern,
  db = NULL,
  fields = c("series_code", "name", "category", "notes"),
  regex = FALSE,
  ignore_case = TRUE,
  metadata = NULL,
  lang = boj_default("lang", "en"),
  cache = TRUE,
  refresh = FALSE,
  max_age = 24 * 60 * 60,
  cache_dir = boj_default("cache_dir", tools::R_user_dir("bojapi", "cache")),
  include_groups = FALSE,
  wait = boj_default("wait", 1),
  timeout = boj_default("timeout", 30),
  retries = boj_default("retries", 3)
)

Arguments

pattern	One non-empty search string or regular expression.
db	One or more database identifiers. Not needed when metadata is supplied.
fields	Metadata columns to search. Defaults to series code, name, category, and notes.
regex	Treat pattern as a regular expression. The default performs a literal substring search.
ignore_case	Ignore letter case.
metadata	Optional data frame returned by boj_metadata() or boj_cache().
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.
cache	Whether to read and write the on-disk metadata cache.
refresh	If TRUE, ignore an existing cache entry.
max_age	Maximum cache age in seconds; default 86,400 (24 hours).
cache_dir	Metadata cache directory.
include_groups	Include matching hierarchy-heading rows.
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.

Value

A filtered metadata tibble.

Examples

## Not run: 
boj_search("U.S. Dollar", db = "FM08")
boj_search("FXERM07", db = "FM08", lang = "jp")
boj_search("exchange|euro", db = "FM08", regex = TRUE)

## End(Not run)

---