Getting started with bojapi

bojapi provides an unofficial R interface to the Bank of Japan Time-Series Data Search API. The API does not require authentication.

Discover a series

Start with a database and search its metadata. Metadata are cached for 24 hours by default to reduce traffic to the BOJ service.

library(bojapi)

boj_databases()
fx_metadata <- boj_metadata("FM08")
boj_search("U.S. Dollar", metadata = fx_metadata)

Use lang = "jp" for Japanese names, units, categories, and notes.

boj_search("米ドル", db = "FM08", lang = "jp")

Retrieve observations

Supply series codes without a database prefix. Named vectors create stable, analysis-friendly aliases while retaining the original code.

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

The long result preserves the exact BOJ period identifier in time. The date column is frequency-aware and uses the first day of a period. For example, quarter 202402 becomes April 1, 2024; fiscal year 2024 becomes April 1, 2024. Use time when the original statistical period is the relevant object.

Wide output is available as a convenience:

boj_data(
  "FM08",
  c(month_end = "FXERM06", monthly_average = "FXERM07"),
  start_date = "202401",
  end_date = "202412",
  wide = TRUE
)

Retrieve a hierarchy

Metadata include hierarchy headings and layer1 through layer5. Pass the desired path, including "*" wildcards, to boj_layer().

bp <- boj_metadata("BP01", include_groups = TRUE)
boj_layer(
  db = "BP01",
  frequency = "M",
  layer = c(1, 1, 1),
  start_date = "202504",
  end_date = "202509"
)

The BOJ rejects a layer condition matching more than 1,250 series before the frequency filter is applied. Split very broad hierarchy requests into narrower paths.

Be a considerate API user

The BOJ prohibits excessive access frequency. bojapi waits at least one second between automatic pages and 250-code chunks. You may increase the delay globally:

options(bojapi.wait = 2)

Expired or invalid metadata cache files are removed when encountered. To manage the cache explicitly, use boj_cache(action = "prune") or boj_cache(action = "clear").

Before publishing a service, read the current official notice. It asks service publishers to display a specified credit and notify the BOJ Research and Statistics Department.

boj_api_credit("en")
boj_api_credit("jp")