SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsboj-statistics

boj-statistics

Data & analytics

View repository

Updated 10-15 17:23

About this skill

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

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

  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.