boj-client 0.3.1

Rust client for the Bank of Japan time-series statistics API
Documentation

日本語 | English

boj-client

CI Nightly Contract Test License: MIT

サポート

Buy Me a Coffee

このOSSが役に立ったら、開発継続のための支援をお願いします。

日本銀行「時系列統計データ検索サイト API機能」（2026年2月18日提供開始）を利用するための、Rust向け非公式APIクライアントです。

このクレートについて

boj-client は、日本銀行の時系列統計データ取得をRustアプリケーションへ組み込みやすくすることを目的としたクライアントです。API仕様に沿ったリクエスト生成とレスポンス処理を提供し、利用者はデータ取得ロジックをシンプルに実装できます。

主な機能

  • 日本銀行APIに対するリクエスト組み立ての簡素化
  • APIレスポンスの取り扱いをRust向けに整理
  • 公式マニュアルをMarkdown化した補助ドキュメントを同梱

インストール

crates.io で公開しています。Cargo.toml に追加してください。

[dependencies]
boj-client = "0.3.0"

公式情報（参照元）

位置づけ（非公式クライアント）

  • boj-client は、日本銀行が提供する「時系列統計データ検索サイト API機能」を利用するための非公式（BOJ非公認）クライアントです。
  • 利用条件・制限事項・免責/保証範囲は、上記の日本銀行公式文書を優先してください。

重要事項（利用条件・免責）

  • 本ソフトウェアの利用方法、仕様解釈、運用判断は、日本銀行（BOJ）の公式文書および最新の公表内容・決定に従ってください。
  • 本READMEや実装内容と、日本銀行の公表内容・決定に差異がある場合は、日本銀行の内容を優先します。
  • 日本銀行（BOJ）から本ソフトウェアに関する要請があった場合、作成者は予告なく当該要請に従います。これに伴い、仕様・提供内容・公開状態などを変更することがあります。
  • 法令上許される範囲で、本ソフトウェアの作成者は、本ソフトウェアの利用または利用不能に起因して生じたいかなる損害についても責任を負いません。

クイックリンク

クイックスタート

返却型は API ごとに分かれています。

  • get_data_code -> CodeResponse
  • get_data_layer -> LayerResponse
  • get_metadata -> MetadataResponse
use boj_client::client::BojClient;
use boj_client::query::{CodeQuery, Format, Language};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = BojClient::new()?;
    let query = CodeQuery::new("CO", vec!["TK99F1000601GCQ01000".to_string()])?
        .with_format(Format::Json)
        .with_lang(Language::En)
        .with_start_date("202401")?
        .with_end_date("202401")?;

    let _response = client.get_data_code(&query)?;
    Ok(())
}

MCPサーバー（stdio / npx）

このリポジトリには、boj-client を MCP 経由で利用するための boj-mcp-server（Rustバイナリ）と、npx ランチャー @explorrrr/boj-mcp-server が同梱されています。

提供ツール

  • boj_get_data_code
  • boj_get_data_layer
  • boj_get_metadata
  • boj_list_databases
  • boj_get_parameter_catalog
  • boj_get_message_catalog

すべてのツールは outputSchema / annotations / execution.taskSupport=forbidden を公開します。

追加MCP IF

  • Prompts:
    • boj_discovery_flow
    • boj_fetch_data_code_flow
    • boj_latest_value_flow
  • Resources:
    • boj://guide/call-order
    • boj://guide/input-normalization
    • boj://catalog/databases
  • Resource templates:
    • boj://catalog/parameters/{endpoint}
    • boj://catalog/messages/{status}
  • Completion:
    • db / format / lang / endpoint / status / frequency

npx実行

npx -y @explorrrr/boj-mcp-server --help

ローカル開発実行（Rust）

cargo run -p boj-mcp-server

MCPクライアント設定例（npx）

{
  "mcpServers": {
    "boj": {
      "command": "npx",
      "args": ["-y", "@explorrrr/boj-mcp-server"]
    }
  }
}

ランチャー用環境変数

  • BOJ_MCP_SERVER_PATH: 既存バイナリを直接使う（ダウンロードをスキップ）
  • BOJ_MCP_CACHE_DIR: ダウンロード済みバイナリのキャッシュ先
  • BOJ_MCP_RELEASE_BASE_URL: 取得元のReleaseベースURL（既定: https://github.com/explorrrr/boj-client/releases/download）

サポート対象

  • linux-x64
  • darwin-x64
  • darwin-arm64
  • win32-x64

メンテナー向けリリース運用

保護ブランチ前提の公式フローは次の通りです。

  1. 版上げは必ずPRで実施し、master にマージします（workflowで版上げしません）。
  2. release-publish.yml を workflow_dispatch で実行します。
    • 入力 version: ルート Cargo.toml の version と一致必須
    • 入力 dry_run=true: release gate（fmt/clippy/doc/test/doc-test/contract/publish dry-run）のみ実行
    • 入力 dry_run=false: gate 通過後に crates.io へ publish
  3. MCP配布が必要な場合は mcp-release.yml を実行します。
    • 入力 version: mcp-server/Cargo.toml と npm/boj-mcp-server/package.json の両方と一致必須
    • publish_npm=false: GitHub Release assets のみ公開
    • publish_npm=true: assets公開後に npm 公開を実行（npm失敗時も summary で assets成功状態を確認可能）

release-publish.yml の crates.io 公開と、mcp-release.yml の npm 公開は GitHub Actions OIDC Trusted Publisher を使用するため、CRATES_IO_TOKEN / NPM_TOKEN は不要です（公開ジョブには id-token: write が必要です）。

include_raw を true にしたときだけ raw を返します。
get_data_code / get_data_layer は単ページ返却で、続き取得は next_position を指定して再実行してください。 ツール実行失敗は JSON-RPC エラーではなく CallToolResult の isError=true と構造化エラーペイロードで返します。 format / lang は JSON / JP のような大文字入力も受理し、内部で小文字正規化します。

推奨呼び出し順（LLM/MCP利用時）:

  1. boj_list_databases でDB候補を取得
  2. boj_get_parameter_catalog で入力制約と上限制約を確認
  3. boj_get_data_code / boj_get_data_layer / boj_get_metadata を実行
  4. 必要に応じて boj_get_message_catalog で MESSAGEID を参照

公開APIノート（0.3.0）

  • Breaking: BojClient::new() は Result<BojClient, BojError> を返すようになりました。

  • Breaking: BojClient の Default 実装を削除しました。

  • 既定の内部HTTPクライアントは 30 秒タイムアウトを設定します。

  • クライアント: boj_client::client::BojClient

  • ディスカバリ辞書: boj_client::catalog::*

  • クエリとオプション: boj_client::query::*

  • レスポンス型: boj_client::model::*

  • decode / transport は内部実装となり、公開されません

開発中のため、仕様詳細はAPI仕様ドキュメントを優先して参照してください。

docs/api-manual は日本銀行の公式API仕様（原本準拠）を参照するための文書群です。docs/design は本クレートのクライアント設計方針（公開IF、バージョン管理、互換性運用）を管理する文書群です。docs/design/api-client-versioning.md は、将来の日銀API仕様変更に備えるためのクライアント側方針案であり、日銀公式のバージョニング仕様そのものを定義する文書ではありません。仕様解釈で差分が出る場合は、まず docs/api-manual を優先し、必要に応じて docs/design を追従更新します。

Contributing

寄稿方法は CONTRIBUTING.md を参照してください。 英語版は CONTRIBUTING.en.md を参照してください。

対応範囲と制約

  • 対象API: 日本銀行「時系列統計データ検索サイト API機能」（2026年2月18日提供開始、上記BOJ告知参照）
  • 本クレートは非公式（BOJ非公認）クライアントです
  • 本リポジトリは、公式仕様に準拠することを優先します
  • 仕様改定時は、公式マニュアルに追従して更新します

開発ステータス

  • ステータス: 開発中
  • 互換性やAPI設計は、リリースまでに調整される可能性があります

README翻訳運用（緩め同期）

  • 片言語のみ先行更新を許可します
  • 未同期で更新する場合、更新したREADMEに次の注記を記載します

注: 英語版は追って同期します。

  • 同期完了時に、上記注記を削除します
  • 言語ごとの更新日時が一致しなくても問題ありません

ライセンス

MIT License。詳細は LICENSE を参照してください。

Last updated: 2026-02-19