Skip to content

API Reference

High-Level Client

BOJ

pyboj._boj.BOJ

High-level client for the Bank of Japan Time-Series Statistics API.

Every parameter is typed — no magic strings. The client fetches metadata, filters series by your criteria, and returns rich domain wrapper objects.

Usage::

from pyboj import BOJ, Currency, Frequency

boj = BOJ()
rates = boj.exchange_rates(currency=Currency.USD_JPY, frequency=Frequency.D)
for r in rates:
    print(r.currency_pair, r.values[:3])
    df = r.to_dataframe()

Or as a context manager::

with BOJ() as boj:
    rates = boj.exchange_rates(currency=Currency.USD_JPY)

__init__(lang=Lang.JP, timeout=DEFAULT_TIMEOUT)

close()

Close the underlying HTTP client.

metadata(db)

Return metadata records for a database.

Parameters

db: Database to query.

exchange_rates(*, currency=None, rate_type=None, frequency=None, start_date=None, end_date=None, db=Database.EXCHANGE_RATES)

Fetch exchange rate series.

Parameters

currency: Filter by currency pair (e.g. Currency.USD_JPY). rate_type: Filter by rate type (e.g. RateType.SPOT_9AM). frequency: Filter by frequency (e.g. Frequency.D). start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: FM08 (Exchange Rates).

interest_rates(*, category=None, collateralization=None, frequency=None, start_date=None, end_date=None, db=Database.CALL_RATES)

Fetch interest rate series.

Parameters

category: Filter by rate category (e.g. RateCategory.CALL_RATE). collateralization: Filter by collateralization type. frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: FM01 (Call Rates).

price_indices(*, index_type=None, frequency=None, start_date=None, end_date=None, db=Database.PRODUCER_PRICE_INDEX)

Fetch price index series.

Parameters

index_type: Filter by index type (e.g. IndexType.PRODUCER). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: PR01 (Producer Price Index).

tankan(*, industry=None, size=None, item=None, series_type=None, timing=None, frequency=None, start_date=None, end_date=None)

Fetch TANKAN survey series.

Parameters

industry: Filter by industry classification. size: Filter by enterprise size. item: Filter by survey item. series_type: Filter by series type (DI, percent point, etc.). timing: Filter by timing (actual vs forecast). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format.

balance_of_payments(*, account=None, frequency=None, start_date=None, end_date=None)

Fetch balance of payments series.

Parameters

account: Filter by BOP account type. frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format.

money_deposits(*, component=None, adjustment=None, frequency=None, start_date=None, end_date=None, db=Database.MONETARY_BASE)

Fetch money and deposit series.

Parameters

component: Filter by monetary component. adjustment: Filter by adjustment type. frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: MD01 (Monetary Base).

loans(*, sector=None, frequency=None, start_date=None, end_date=None, db=Database.LOANS_BY_SECTOR)

Fetch loan series.

Parameters

sector: Filter by industry sector. frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: LA01 (Loans by Sector).

financial_markets(*, segment=None, instrument_type=None, frequency=None, start_date=None, end_date=None, db=Database.SHORT_TERM_MONEY_OUTSTANDING)

Fetch financial markets series (FM03-FM07).

Parameters

segment: Filter by market segment (e.g. MarketSegment.GOVT_BONDS). instrument_type: Filter by instrument type (e.g. InstrumentType.OUTSTANDING). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: FM03.

balance_sheets(*, account_side=None, institution_type=None, frequency=None, start_date=None, end_date=None, db=Database.BOJ_ACCOUNTS)

Fetch balance sheet series (BS01-BS02).

Parameters

account_side: Filter by balance sheet side (e.g. AccountSide.ASSETS). institution_type: Filter by institution type (e.g. InstitutionType.BOJ). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: BS01.

flow_of_funds(*, sector=None, instrument=None, frequency=None, start_date=None, end_date=None)

Fetch flow of funds series (FF).

Parameters

sector: Filter by economic sector (e.g. FofSector.HOUSEHOLDS). instrument: Filter by financial instrument (e.g. FofInstrument.EQUITY). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format.

boj_operations(*, operation_type=None, frequency=None, start_date=None, end_date=None, db=Database.GOVT_TRANSACTIONS)

Fetch BOJ operations series (OB01-OB02).

Parameters

operation_type: Filter by operation type (e.g. OperationType.JGB_OPERATIONS). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: OB01.

public_finance(*, fiscal_item=None, frequency=None, start_date=None, end_date=None, db=Database.TREASURY_RECEIPTS_PAYMENTS)

Fetch public finance series (PF01-PF02).

Parameters

fiscal_item: Filter by fiscal item (e.g. FiscalItem.TAX_REVENUE). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: PF01.

international(*, stat_category=None, frequency=None, start_date=None, end_date=None, db=Database.BIS_BANKING_STATISTICS)

Fetch international statistics series (BIS, DER, PS01, PS02, OT).

Parameters

stat_category: Filter by statistics category (e.g. StatCategory.DERIVATIVES). frequency: Filter by frequency. start_date: Start date in YYYYMM format. end_date: End date in YYYYMM format. db: Database to query. Default: BIS.

layer_tree(db)

Build a hierarchical layer tree from database metadata.

Parameters

db: Database to build the tree for.

Returns

LayerNode Root node of the layer hierarchy.

search(db, query)

Search metadata records by keyword.

Parameters

db: Database to search. query: Case-insensitive search string.

Returns

list[MetadataRecord] Matching metadata records.

Database Enum

pyboj._config.Database

Bases: str, Enum

BOJ Time-Series Statistics database codes.

Each member maps to a database identifier used by the BOJ API. Because Database inherits from str, members can be passed directly to :pymeth:Client.get_data_code as the db argument.

Domain Wrappers

Base

pyboj._domains._base.Series

Base class for domain wrapper objects.

Wraps a :class:~boj_ts_api.SeriesResult and provides parsed dates, cleaned numeric values, and optional DataFrame conversion.

series_code property

name property

English series name.

name_jp property

Japanese series name.

unit property

frequency property

category property

dates property

Survey dates parsed into :class:datetime.date objects.

Entries where the raw date is None are excluded, along with their corresponding values, to keep dates and values aligned.

values property

Numeric values with non-numeric entries converted to None.

Entries where the corresponding date is None are excluded.

to_dataframe()

Return a :class:pandas.DataFrame with a DatetimeIndex.

Returns

pandas.DataFrame Single column value indexed by date.

plot(*, lang=None, title=None, ylabel=None, figsize=(10, 4), **kwargs)

Plot this series.

Parameters

lang: Language for labels (Lang.JP or Lang.EN). Defaults to the language set on the BOJ client. title: Custom chart title. ylabel: Custom y-axis label. figsize: Figure size (width, height) in inches. **kwargs: Passed to ax.plot().

Returns

matplotlib.axes.Axes

ExchangeRate

pyboj._domains.exchange_rate.ExchangeRate

Bases: Series

Domain wrapper for exchange rate series (FM08 / FM09).

currency_pair property

ISO currency pair (e.g. Currency.USD_JPY) or None.

rate_type property

Classified rate type based on the English series name.

pyboj._domains.exchange_rate.Currency

Bases: str, Enum

ISO currency pair for exchange rate series.

pyboj._domains.exchange_rate.RateType

Bases: str, Enum

Type of exchange rate observation.

InterestRate

pyboj._domains.interest_rate.InterestRate

Bases: Series

Domain wrapper for interest rate series (FM01, FM02, IR01-IR04).

collateralization property

Collateralization type, or None if not applicable.

rate_category property

Classified rate category based on the English series name.

tenor property

Extracted tenor string (e.g. "overnight", "3M"), or None.

pyboj._domains.interest_rate.RateCategory

Bases: str, Enum

High-level classification of the interest rate.

pyboj._domains.interest_rate.Collateralization

Bases: str, Enum

Whether the rate is collateralized or uncollateralized.

PriceIndex

pyboj._domains.price_index.PriceIndex

Bases: Series

Domain wrapper for price index series (PR01-PR04).

base_year property

Base year string (e.g. "CY2020") extracted from the unit, or None.

index_type property

Classified index type based on the English series name and category.

is_yoy_change property

True when the series represents year-on-year percentage change.

pyboj._domains.price_index.IndexType

Bases: str, Enum

High-level classification of the price index.

Tankan

pyboj._domains.tankan.Tankan

Bases: Series

Domain wrapper for TANKAN survey series (CO database).

industry property

Detected industry classification.

item property

Detected survey item.

series_type property

Detected series type (DI, percent point, etc.).

size property

Detected enterprise size, or None if not identifiable.

timing property

Detected timing (actual vs forecast).

pyboj._domains.tankan.TankanIndustry

Bases: str, Enum

TANKAN industry classification.

pyboj._domains.tankan.TankanSize

Bases: str, Enum

TANKAN enterprise size classification.

pyboj._domains.tankan.TankanItem

Bases: str, Enum

TANKAN survey item.

pyboj._domains.tankan.TankanSeriesType

Bases: str, Enum

TANKAN series type.

pyboj._domains.tankan.TankanTiming

Bases: str, Enum

TANKAN survey timing.

BalanceOfPayments

pyboj._domains.balance_of_payments.BalanceOfPayments

Bases: Series

Domain wrapper for balance of payments series (BP01).

account property

Detected BOP account type.

pyboj._domains.balance_of_payments.BopAccount

Bases: str, Enum

Balance of payments account classification.

MoneyDeposit

pyboj._domains.money_deposit.MoneyDeposit

Bases: Series

Domain wrapper for money and deposit series (MD01-MD14).

adjustment property

Detected adjustment type.

component property

Detected monetary component.

pyboj._domains.money_deposit.MonetaryComponent

Bases: str, Enum

Monetary aggregate component.

pyboj._domains.money_deposit.Adjustment

Bases: str, Enum

Statistical adjustment type.

Loan

pyboj._domains.loan.Loan

Bases: Series

Domain wrapper for loan series (LA01-LA05).

sector property

Detected industry sector.

pyboj._domains.loan.IndustrySector

Bases: str, Enum

Industry sector classification for loan data.

FinancialMarket

pyboj._domains.financial_market.FinancialMarket

Bases: Series

Domain wrapper for financial markets series (FM03-FM07).

instrument_type property

Detected instrument type.

segment property

Detected market segment.

pyboj._domains.financial_market.MarketSegment

Bases: str, Enum

Financial market segment classification.

pyboj._domains.financial_market.InstrumentType

Bases: str, Enum

Financial instrument classification.

BalanceSheet

pyboj._domains.balance_sheet.BalanceSheet

Bases: Series

Domain wrapper for balance sheet series (BS01-BS02).

account_side property

Detected balance sheet side (assets/liabilities).

institution_type property

Detected institution type.

pyboj._domains.balance_sheet.AccountSide

Bases: str, Enum

Balance sheet side classification.

pyboj._domains.balance_sheet.InstitutionType

Bases: str, Enum

Financial institution type.

FlowOfFunds

pyboj._domains.flow_of_funds.FlowOfFunds

Bases: Series

Domain wrapper for flow of funds series (FF).

instrument property

Detected financial instrument.

sector property

Detected economic sector.

pyboj._domains.flow_of_funds.FofSector

Bases: str, Enum

Flow of funds sector classification.

pyboj._domains.flow_of_funds.FofInstrument

Bases: str, Enum

Flow of funds financial instrument classification.

BOJOperation

pyboj._domains.boj_operation.BOJOperation

Bases: Series

Domain wrapper for BOJ operations series (OB01-OB02).

operation_type property

Detected operation type.

pyboj._domains.boj_operation.OperationType

Bases: str, Enum

BOJ operation type classification.

PublicFinance

pyboj._domains.public_finance.PublicFinance

Bases: Series

Domain wrapper for public finance series (PF01-PF02).

fiscal_item property

Detected fiscal item classification.

pyboj._domains.public_finance.FiscalItem

Bases: str, Enum

Public finance item classification.

InternationalStat

pyboj._domains.international_stat.InternationalStat

Bases: Series

Domain wrapper for international statistics series (BIS, DER, PS01, PS02, OT).

stat_category property

Detected statistics category.

pyboj._domains.international_stat.StatCategory

Bases: str, Enum

International statistics category classification.

Discovery

Layer Tree

pyboj._helpers.layer_tree.LayerNode dataclass

A node in the BOJ metadata layer hierarchy.

Attributes

level: Hierarchy level (0 = root). code: Layer code from the metadata. name: Human-readable name for this layer. children: Child nodes in the hierarchy. series_codes: Series codes belonging directly to this node (leaf level).

pyboj._helpers.layer_tree.build_layer_tree(records)

Build a hierarchical tree from flat BOJ metadata records.

The BOJ API returns metadata as a flat list where hierarchy is encoded in the record ordering and LAYER1-LAYER5 fields. Header rows (SERIES_CODE is None) define layer nodes; data rows define leaf series.

Parameters

records: Metadata records from :meth:BOJ.metadata or :meth:Client.get_metadata.

Returns

LayerNode Root node of the layer tree.

pyboj._helpers.layer_tree.search_metadata(records, query)

Search metadata records by keyword (case-insensitive substring match).

Searches across series code, English name, Japanese name, and category.

Parameters

records: Metadata records to search. query: Search string (case-insensitive).

Returns

list[MetadataRecord] Matching records (only rows with a series code).

Low-Level Clients

Synchronous

boj_ts_api.client.Client

Bases: _BaseClient

Synchronous client for the Bank of Japan Time-Series API.

Usage::

with Client(lang=Lang.EN) as client:
    resp = client.get_data_code(db="CO", code="TK99F1000601GCQ01000")

get_data_code(db, code, *, start_date=None, end_date=None, start_position=None)

Fetch time-series data by series code(s). Returns a single page.

iter_data_code(db, code, *, start_date=None, end_date=None)

Iterate over all series results, auto-paginating via NEXTPOSITION.

get_data_code_csv(db, code, *, start_date=None, end_date=None, start_position=None)

Fetch time-series data as raw CSV text.

get_data_layer(db, frequency, layer, *, start_date=None, end_date=None, start_position=None)

Fetch time-series data by hierarchy layer. Returns a single page.

iter_data_layer(db, frequency, layer, *, start_date=None, end_date=None)

Iterate over all series results from Layer API, auto-paginating.

get_data_layer_csv(db, frequency, layer, *, start_date=None, end_date=None, start_position=None)

Fetch layer data as raw CSV text.

get_metadata(db)

Fetch metadata for a database.

get_metadata_csv(db)

Fetch metadata as raw CSV text.

close()

Asynchronous

boj_ts_api.async_client.AsyncClient

Bases: _BaseClient

Asynchronous client for the Bank of Japan Time-Series API.

Usage::

async with AsyncClient(lang=Lang.EN) as client:
    resp = await client.get_data_code(db="CO", code="TK99F1000601GCQ01000")

get_data_code(db, code, *, start_date=None, end_date=None, start_position=None) async

Fetch time-series data by series code(s). Returns a single page.

iter_data_code(db, code, *, start_date=None, end_date=None) async

Iterate over all series results, auto-paginating via NEXTPOSITION.

get_data_code_csv(db, code, *, start_date=None, end_date=None, start_position=None) async

Fetch time-series data as raw CSV text.

get_data_layer(db, frequency, layer, *, start_date=None, end_date=None, start_position=None) async

Fetch time-series data by hierarchy layer. Returns a single page.

iter_data_layer(db, frequency, layer, *, start_date=None, end_date=None) async

Iterate over all series results from Layer API, auto-paginating.

get_data_layer_csv(db, frequency, layer, *, start_date=None, end_date=None, start_position=None) async

Fetch layer data as raw CSV text.

get_metadata(db) async

Fetch metadata for a database.

get_metadata_csv(db) async

Fetch metadata as raw CSV text.

close() async

Response Models

boj_ts_api._types.models.response.DataResponse

Bases: ResponseEnvelope

Envelope for Code/Layer API JSON responses.

boj_ts_api._types.models.response.MetadataResponse

Bases: ResponseEnvelope

Envelope for Metadata API JSON responses.

boj_ts_api._types.models.series.SeriesResult

Bases: BOJBaseModel

A single series item from the RESULTSET of Code/Layer endpoints.

boj_ts_api._types.models.series.SeriesValues

Bases: BOJBaseModel

Nested time-series values within a series result.

boj_ts_api._types.models.metadata.MetadataRecord

Bases: BOJBaseModel

A single metadata record from the RESULTSET of the Metadata endpoint.

Enums

boj_ts_api._types.config.Lang

Bases: str, Enum

Language for API responses.

boj_ts_api._types.config.Format

Bases: str, Enum

Response format.

boj_ts_api._types.config.Frequency

Bases: str, Enum

Time-series frequency.

Exceptions

boj_ts_api._types.exceptions.BOJError

Bases: Exception

Base exception for all BOJ API errors.

boj_ts_api._types.exceptions.BOJAPIError

Bases: BOJError

Raised when the API returns a non-200 STATUS.

boj_ts_api._types.exceptions.BOJRequestError

Bases: BOJError

Raised on network / transport errors.

boj_ts_api._types.exceptions.BOJValidationError

Bases: BOJError

Raised when request parameters fail local validation.

Plotting

pyboj._plotting._plot.plot_series(*series, lang=None, title=None, ylabel=None, figsize=(10, 4), **kwargs)

Plot one or more Series on a single Axes.

Parameters

series: One or more :class:~pyboj.Series objects to plot. lang: Language for auto-generated labels. Defaults to the language set by :func:set_default_lang (which follows BOJ(lang=...)). title: Custom chart title. If None and a single series is plotted, the series name is used. ylabel: Custom y-axis label. If None and a single series is plotted, the series unit is used. figsize: Figure size (width, height) in inches. *kwargs: Passed to ax.plot().

Returns

matplotlib.axes.Axes

pyboj._plotting._plot.set_default_lang(lang)

Set the default language for plot labels.

Called automatically by :class:~pyboj.BOJ on initialization so that the plotting language matches the client language.

Utilities

pyboj._helpers.csv.csv_to_dataframe(csv_text, *, encoding='utf-8')

Convert CSV text from the BOJ API into a pandas DataFrame.

Parameters

csv_text: Raw CSV text returned by a *_csv() client method. Accepts str (already decoded) or bytes (decoded using encoding). encoding: Encoding for csv_text when it is bytes. The BOJ API uses UTF-8 for English (lang=en) and Shift-JIS for Japanese (lang=jp). Use encoding="shift_jis" for Japanese CSV responses.

Returns

pandas.DataFrame