boj-api 0.1.2

A production-ready Python client for the Bank of Japan (BOJ) Time-Series Statistics Search Site API.

boj-api

A production-ready Python client for the Bank of Japan (BOJ) Time-Series Statistics Search Site API.

This library provides a clean, typed, and well-documented interface to all three BOJ statistical data APIs:

API	Method	Description
Code API	get_data_by_code()	Fetch time-series data by series codes
Layer API	get_data_by_layer()	Fetch time-series data by hierarchy/layer
Metadata API	get_metadata()	Fetch database metadata (series names, units, layers, etc.)

Credit: This library uses the Bank of Japan Time-Series Statistics Search Site API. The content is not guaranteed by the Bank of Japan.

「このサービスは、日本銀行時系列統計データ検索サイトのAPI機能を使用しています。 サービスの内容は日本銀行によって保証されたものではありません。」

Installation

pip install boj-api

Quick Start

from boj_api import BOJClient, Database, Frequency

client = BOJClient()

# Fetch exchange rate data (Code API)
response = client.get_data_by_code(
    db=Database.FM08,
    code=["FXERD01", "FXERD02"],
    start_date="202401",
    end_date="202412",
)

for series in response.series:
    print(f"{series.name_jp}: {len(series.observations)} observations")

# Fetch data by layer hierarchy (Layer API)
response = client.get_data_by_layer(
    db=Database.BP01,
    frequency=Frequency.MONTHLY,
    layer=[1, 1, 1],
    start_date="202504",
    end_date="202509",
)

# Fetch metadata for a database (Metadata API)
metadata = client.get_metadata(db=Database.FM08)
for entry in metadata.entries:
    print(f"{entry.series_code}: {entry.name_jp}")

Auto-Pagination

The BOJ API limits results to 250 series / 60,000 data points per request. BOJClient handles pagination automatically:

# Automatically follows NEXTPOSITION until all data is fetched
all_data = client.get_data_by_code(
    db=Database.CO,
    code=series_codes,  # can exceed 250
    auto_paginate=True,
)

Databases

All BOJ database identifiers are available as the Database enum:

Enum	DB Name	Description
Database.IR01	IR01	Base discount/loan rates
Database.FM01	FM01	Uncollateralized overnight call rate
Database.FM08	FM08	Foreign exchange rates
Database.CO	CO	Tankan survey
Database.FF	FF	Flow of funds
...	...	See boj_api.enums.Database for full list

Frequency Types

Enum	Code	Description
Frequency.CALENDAR_YEAR	CY	Calendar year
Frequency.FISCAL_YEAR	FY	Fiscal year
Frequency.SEMI_ANNUAL_CY	CH	Semi-annual (calendar)
Frequency.SEMI_ANNUAL_FY	FH	Semi-annual (fiscal)
Frequency.QUARTERLY	Q	Quarterly
Frequency.MONTHLY	M	Monthly
Frequency.WEEKLY	W	Weekly
Frequency.DAILY	D	Daily

Date Formats

The start_date / end_date format depends on the frequency of the series:

Frequency	Format	Example
Daily, Monthly, Quarterly, Semi-annual	YYYYMM	"202401"
Calendar year, Fiscal year	YYYY	"2024"

Note: YYYYMMDD (8-digit) dates are never accepted by the API.

API Reference

BOJClient

BOJClient(
    lang: Language = Language.JP,
    format: Format = Format.JSON,
    timeout: float = 30.0,
    max_retries: int = 3,
    retry_delay: float = 1.0,
)

Error Handling

from boj_api import BOJClient, BOJAPIError, InvalidParameterError

client = BOJClient()
try:
    data = client.get_data_by_code(db="INVALID", code=["X"])
except InvalidParameterError as e:
    print(f"Bad request: {e.message_id} - {e.message}")
except BOJAPIError as e:
    print(f"API error: {e}")

Development

# Clone the repository
git clone https://github.com/YenAle-FT-Gmail/BOJ_API_Python.git
cd BOJ_API_Python

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint & format
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

License

MIT License. See LICENSE for details.

Links

• BOJ API Announcement (2026-02-18)
• API Manual (PDF)
• API Usage Notice (PDF)
• BOJ Time-Series Statistics Search Site