Package {bojapi}

bojapi: Bank of Japan time-series data for R

Description

bojapi is an unofficial, independently developed client for the official Bank of Japan (BOJ) Time-Series Data Search API. It is not affiliated with, endorsed by, or maintained by the Bank of Japan. It provides a small workflow:

Details

1. List databases with boj_databases().

2. Discover series with boj_search() or boj_metadata().

3. Retrieve observations with boj_data() or boj_layer().

The BOJ API requires no API key. To respect the BOJ prohibition on high-frequency access, automatic multi-request operations wait at least one second between requests. Increase this per call with wait, or globally with options(bojapi.wait = 2); values below one are treated as one.

Package options

• bojapi.lang: default response language, "en" or "jp".

• bojapi.wait: requested seconds between automatic requests; default and enforced minimum 1.

• bojapi.timeout: request timeout in seconds; default 30.

• bojapi.retries: retries for transient failures; default 3.

• bojapi.cache_dir: metadata cache directory.

Terms of use

Public services using the API must follow the BOJ's current API notice, including its requested credit and release notification. Use boj_api_credit() to retrieve the credit and official links. The package's MIT license applies to original bojapi code and documentation; it does not relicense BOJ-originated or other third-party content.

Author(s)

Maintainer: Kenji Miyazaki kenjimyzk@gmail.com

Authors:

• Kenji Miyazaki kenjimyzk@gmail.com

See Also

BOJ API manual, BOJ API notice

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

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

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

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

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

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

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)