Boj Statistics

BOJ Statistics Skill

Retrieve and analyze time-series statistical data from the Bank of Japan API.

Workflow overview

1. Determine the user's intent: explore databases, search series, fetch data, or get latest values.
2. Identify the target DB name — consult references/db_list.md to find the right DB without running a command. For example, exchange rates are in FM08, Tankan is CO, balance of payments is BP01.
3. Execute scripts/boj_statistics_cli.py via uv run --project scripts with the appropriate sub-command.
4. Present results as a table, summary, or raw data depending on context.

Available sub-commands

1 — Explore available databases

uv run --project scripts scripts/boj_statistics_cli.py list-db [--format json|csv|tsv|table] [--lang jp|en]

Returns the full list of BOJ database names and descriptions.

2 — Get metadata for a database

uv run --project scripts scripts/boj_statistics_cli.py get-metadata --db <DB_NAME> [--format json|csv|tsv|table] [--lang jp|en]

Returns all series codes, names, frequencies, and coverage periods for the specified DB.

3 — Search series by keyword

uv run --project scripts scripts/boj_statistics_cli.py search-series --db <DB_NAME> --keywords <kw1> [<kw2> ...] [--format json|csv|tsv|table] [--lang jp|en]

Searches series names (OR match, case-insensitive) within the specified DB. Useful when the user describes what data they want but doesn't know the series code.

Use --db all to search across all 50 databases at once — useful when the user doesn't know which DB contains the data they need. This takes longer (~2 minutes) due to rate limiting but eliminates the need to check list-db first.

uv run --project scripts scripts/boj_statistics_cli.py search-series --db all --keywords マネタリーベース --format table --max-series-size 10

4 — Fetch time-series data by code

uv run --project scripts scripts/boj_statistics_cli.py get-data --db <DB_NAME> --code <CODE1>[,<CODE2>,...] [--start <YYYYMM>] [--end <YYYYMM>] [--format json|csv|tsv|table] [--lang jp|en]

Fetches actual data values. Pagination is handled automatically. Codes are comma-separated. All codes in a single request must share the same frequency — if you need to mix frequencies, make separate calls.

Date format depends on the series frequency (see references/api_spec.md § Frequency Codes):

• Annual: YYYY (e.g. 2024)
• Half-year / Quarterly: YYYYHH / YYYYQQ (e.g. 202401)
• Monthly / Weekly / Daily: YYYYMM (e.g. 202503)

5 — Fetch time-series data by layer

uv run --project scripts scripts/boj_statistics_cli.py get-layer --db <DB_NAME> --layer <LAYER_INFO> --frequency <FREQ> [--start <YYYYMM>] [--end <YYYYMM>] [--format json|csv|tsv|table] [--lang jp|en]

Layer info examples: 1,1,1 (specific path), * (all). Up to 5 levels can be specified.

The --frequency parameter is required and must be one of: CY, FY, CH, FH, Q, M, W, D. See references/api_spec.md § Frequency Codes for the full mapping. Use get-metadata first to check which frequencies a DB actually contains — not every DB has every frequency.

6 — Get latest data point

uv run --project scripts scripts/boj_statistics_cli.py latest --db <DB_NAME> --code <CODE1>[,<CODE2>,...] [--format json|csv|tsv|table] [--lang jp|en]

Returns only the most recent observation for each series. Useful for quick lookups.

Common options

Pagination is automatic — the script follows NEXTPOSITION tokens across multiple requests. See references/api_spec.md § Pagination for API limits (250 series / 60,000 data points per request).

Typical workflow

1. If the user wants to explore: run list-db → get-metadata → search-series
2. If the user doesn't know which DB to search: run search-series --db all --keywords <terms> to search across all databases
3. If the user knows the series: run get-data or latest directly
4. If the user wants hierarchical data: run get-layer
5. Use --max-series-size and --max-item-length to control output size for large datasets

Use case examples

Get exchange rate trends

uv run --project scripts scripts/boj_statistics_cli.py search-series --db FM08 --keywords ドル 円
uv run --project scripts scripts/boj_statistics_cli.py get-data --db FM08 --code FXERD01 --start 202401 --end 202412 --format table

Get Tankan business conditions DI

uv run --project scripts scripts/boj_statistics_cli.py search-series --db CO --keywords 業況 大企業 製造業
uv run --project scripts scripts/boj_statistics_cli.py get-data --db CO --code TK99F1000601GCQ01000 --start 202401 --end 202504 --format table

Explore series by keyword

uv run --project scripts scripts/boj_statistics_cli.py search-series --db BP01 --keywords 経常収支 --format table

Gotchas

• Series codes do NOT include the DB name prefix. Use FXERD01, not FM08'FXERD01.
• All series in a single get-data request must share the same frequency.
• Weekly/daily date parameters use monthly format (YYYYMM).
• The API blocks high-frequency access. The script enforces rate limiting automatically.
• Metadata results include hierarchy header rows with empty series_code — these are structural, not data.

Error handling

Errors are output to stderr as JSON with error, message, status_code, message_id, and api_message fields. See references/api_spec.md for the full error code table.

Script reference

• Script: scripts/boj_statistics_cli.py (Python 3.11+, run via uv run --project scripts)
• Package: scripts/boj_statistics/ (client library)
• Dependencies: None (Python standard library only)
• Logging: Set LOG_LEVEL env var (DEBUG, INFO, WARN, ERROR). Default: WARN.
• Sample prompts: See references/sample-trigger.md for realistic trigger examples with outputs.