Metadata-Version: 2.4
Name: boj-api
Version: 0.1.2
Summary: A production-ready Python client for the Bank of Japan (BOJ) Time-Series Statistics Search Site API.
Author: Kenta Aratani
License: MIT
Project-URL: Homepage, https://github.com/YenAle-FT-Gmail/BOJ_API_Python
Project-URL: Repository, https://github.com/YenAle-FT-Gmail/BOJ_API_Python
Project-URL: Issues, https://github.com/YenAle-FT-Gmail/BOJ_API_Python/issues
Keywords: boj,bank-of-japan,statistics,api,time-series,economics,finance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install boj-api
```

## Quick Start

```python
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:

```python
# 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`

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

### Error Handling

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

```bash
# 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](LICENSE) for details.

## Links

- [BOJ API Announcement (2026-02-18)](https://www.boj.or.jp/statistics/outline/notice_2026/not260218a.htm)
- [API Manual (PDF)](https://www.stat-search.boj.or.jp/info/api_manual.pdf)
- [API Usage Notice (PDF)](https://www.stat-search.boj.or.jp/info/api_notice.pdf)
- [BOJ Time-Series Statistics Search Site](https://www.stat-search.boj.or.jp/index.html)
