English | 日本語

bojapi

bojapi is an unofficial R package for accessing the official API of the Bank of Japan Time-Series Data Search site. No API key is required.

Its primary workflow is similar to WDI: search the metadata to find series codes, specify a period, and retrieve the observations as a data frame. The package uses JSON internally, avoiding differences in Japanese CSV encodings and the API behavior of returning errors as JSON even when CSV is requested.

Features

• boj_search(): Search series names, codes, categories, and notes
• boj_data(): Retrieve time series by series code
• boj_layer(): Retrieve multiple series using the five-level hierarchy
• boj_metadata(): Retrieve normalized metadata, including hierarchy, coverage, update dates, and notes
• boj_cache(): Refresh, prune, or clear metadata in a WDIcache-style workflow
• Automatic batching in groups of 250 series and complete NEXTPOSITION pagination
• Missing values retained as observation rows containing NA
• Series aliases through named vectors, with long and wide output
• Frequency-aware date conversion for daily, weekly, monthly, quarterly, calendar-half-year, fiscal-half-year, calendar-year, and fiscal-year data
• gzip compression, timeouts, retries, and a default one-second delay between pages
• English and Japanese API responses

Installation

Install the development version from the repository root:

install.packages("remotes")
remotes::install_local(".")

Install the development version from GitHub with:

remotes::install_github("kenjimyzk/bojapi")

Quick start

library(bojapi)

# 1. List available databases
boj_databases()

# 2. Search for a series code (the metadata are cached for 24 hours)
boj_search("U.S. Dollar", db = "FM08")
boj_search("米ドル", db = "FM08", lang = "jp")

# 3. Retrieve monthly U.S. dollar/yen exchange rates
fx <- boj_data(
  db = "FM08",
  code = c(usd_yen = "FXERM07"),
  start_date = "202401",
  end_date = "202412",
  lang = "en"
)

fx

Supply series codes without the database prefix. All codes in a single boj_data() call must have the same frequency.

In long output, time preserves the original BOJ period code and date contains a parsed date for analysis. For quarterly data, 202402 means the second quarter of 2024, not February 2024, so it becomes date = 2024-04-01.

# Retrieve multiple series in wide format
fx_wide <- boj_data(
  "FM08",
  c(month_end = "FXERM06", monthly_average = "FXERM07"),
  start_date = "202401",
  end_date = "202412",
  lang = "en",
  wide = TRUE
)

Hierarchy API

You can retrieve a category of series using metadata fields layer1 through layer5, without listing every series code individually.

meta <- boj_metadata("BP01", lang = "en", include_groups = TRUE)

balance_of_payments <- boj_layer(
  db = "BP01",
  frequency = "M",
  layer = c(1, 1, 1),
  start_date = "202504",
  end_date = "202509",
  lang = "en"
)

The BOJ API returns an error when a hierarchy condition matches more than 1,250 series. This limit is evaluated before the frequency filter. If it is exceeded, split the query by the first hierarchy level or another suitable level.

Comparison with existing R packages

Because a package named BOJ already exists on CRAN, this package is named bojapi.

bojapi is a dedicated client that also handles normalized hierarchy and coverage metadata, missing observations, automatic pagination, and delays between requests.

Both bojapi and bbk export functions named boj_data() and boj_metadata(). If both packages are attached, use bojapi::boj_data() and bojapi::boj_metadata() to select this implementation explicitly.

Request rate and errors

The BOJ prohibits high-frequency access over a short period. When an operation requires multiple requests, bojapi waits at least one second. Values below one are treated as one; increase the interval when appropriate.

options(bojapi.wait = 2, bojapi.timeout = 60, bojapi.retries = 3)

Expired or invalid metadata cache entries are removed when encountered. You can also manage the cache explicitly with boj_cache(action = "prune") or boj_cache(action = "clear").

API errors have class boj_api_response_error, communication errors have class boj_http_error, and unexpected response structures have class boj_parse_error. A no-data response (M181030I) is not an error: the package issues a warning and returns an empty tibble with consistent column types.

Credit for public services

If you publish a service that uses this package, follow the Bank of Japan’s Notice Regarding the Use of the API Service, including displaying the requested credit and notifying the Research and Statistics Department about the release.

boj_api_credit("en")

The terms may change without notice, so always check the official document before publishing a service. The MIT license applies to the original code and documentation authored for bojapi. It does not relicense Bank of Japan data, metadata, database identifiers or names, prescribed credit text, official documents, or other third-party content. See COPYRIGHTS and NOTICE for the source and rights boundaries.

Acknowledgements

bojapi was implemented independently. Its user-facing workflow and package design were informed by the public interfaces and examples of WDI, estatapi, and BOJ_API. We thank their authors and contributors.

API documentation

• API Manual
• Notice Regarding the Use of the API Service
• Japanese API Manual
• Japanese Notice Regarding the Use of the API Service