| name | boj-statistics |
| description | Fetch, search, and analyze time-series statistical data from the Bank of Japan (BOJ) public API. Covers all BOJ databases including interest rates, money markets, foreign exchange, monetary base, Tankan survey, price indices, balance of payments, flow of funds, and more. Use this skill whenever the user wants to retrieve Japanese macroeconomic or financial statistics, look up BOJ data series, check exchange rates, get Tankan DI values, or explore any time-series data published by the Bank of Japan. Also use when the user mentions 日銀, 日本銀行, 時系列統計, 短観, 為替, マネタリーベース, 国際収支, 企業物価, 資金循環, or any BOJ database name (FM08, CO, BP01, etc.). Trigger keywords: BOJ, Bank of Japan, 日銀, 日本銀行, 時系列統計, Tankan, 短観, exchange rate, 為替, interest rate, 金利, monetary base, マネタリーベース, money stock, マネーストック, balance of payments, 国際収支, price index, 物価指数, flow of funds, 資金循環, BOJ statistics, 日銀統計, 統計データ. |
| license | MIT No Attribution |
| compatibility | Requires Python 3.11+ and uv. No external Python packages needed — uses only the standard library. |
| metadata | {"author":"aws-jp-fsi-sa","version":"1.0"} |
BOJ Statistics Skill
Retrieve and analyze time-series statistical data from the Bank of Japan API.
Workflow overview
- Determine the user's intent: explore databases, search series, fetch data, or get latest values.
- 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.
- Execute
scripts/boj_statistics_cli.py via uv run --project scripts with the appropriate sub-command.
- Present results as a table, summary, or raw data depending on context.
Available sub-commands
| Command | Purpose |
|---|
list-db | List all available BOJ databases |
get-metadata | Get series metadata for a specific database |
search-series | Search series by keyword within a database |
get-data | Fetch time-series data by series code (Code API) |
get-layer | Fetch time-series data by layer hierarchy (Layer API) |
latest | Fetch the most recent data point for specified series |
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
| Option | Description | Default |
|---|
--format | Output format: json, csv, tsv, table | json |
--lang | Language: jp, en | jp |
--output | Write to file instead of stdout | stdout |
--max-series-size | Limit number of series in output | unlimited |
--max-item-length | Limit data points per series | unlimited |
--max-pages | Max pagination requests | 20 |
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
- If the user wants to explore: run
list-db → get-metadata → search-series
- If the user doesn't know which DB to search: run
search-series --db all --keywords <terms> to search across all databases
- If the user knows the series: run
get-data or latest directly
- If the user wants hierarchical data: run
get-layer
- 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.
