boj-statistics

Files (26)

• NOTICES.md
• SKILL.md
• SKILL_ja.md
• retrieve-tabulardata.sh · assets/
• pytest.ini
• api_spec.md · references/
• db_list.md · references/
• sample-trigger.md · references/
• __init__.py · scripts/boj_statistics/
• boj_client.py · scripts/boj_statistics/
• constants.py · scripts/boj_statistics/
• exceptions.py · scripts/boj_statistics/
• formatters.py · scripts/boj_statistics/
• models.py · scripts/boj_statistics/
• boj_statistics_cli.py · scripts/
• pyproject.toml · scripts/
• requirements.txt · scripts/
• uv.lock · scripts/
• conftest.py · tests/
• test_all_db.py · tests/
• test_cli.py · tests/
• test_client.py · tests/
• test_exceptions.py · tests/
• test_formatters.py · tests/
• test_integration.py · tests/
• test_models.py · tests/

SKILL.md (first lines)

# 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](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

```bash
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

```bash
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

```bash
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.

```bash
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

```bash
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](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

```bash
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](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

```bash
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](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
```bash
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
```bash
uv run --project scripts scripts/boj_statistics_cli.py search-series --db CO --keywords 業況 大企業 製造業

From aws-samples/sample-fsi-reference-architecture-jp, MIT-0.

More from aws-samples/sample-fsi-reference-architecture-jp