# 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")