FXMacroData

FXMacroData Python SDK 🐍📊

FXMacroData Python SDK は、FXMacroData からマクロ経済指標、外国為替価格、発表カレンダー、COT ポジションデータ、商品価格を取得するための、シンプルで効率的なインターフェースを提供します。

同期クライアントと非同期クライアントを使用して、研究用ノートブック、バックテスト、アプリケーションにデータを取り込めます。

USD 以外のデータ、利用可能な全期間の履歴、外国為替、商品、ポジションデータを利用するには、FXMacroData に登録してください。サブスクリプションに接続する前に、公開 USD ワークフローで連携を評価できます。

---

🌟 特長

• 取得できるデータ：
  • マクロ経済指標 — 政策金利、インフレ率、GDP、失業率、債券利回りなど：656 のエンドポイントにわたる 97 種類の指標
  • 外国為替スポットレート（オプションでテクニカル指標も利用可能：SMA、RSI、MACD、ボリンジャーバンド）
  • 発表カレンダー — 今後発表される経済データの日付
  • データカタログ — 通貨ごとに利用可能な指標を確認
  • COT データ — CFTC のトレーダー建玉データ
  • 商品価格 — 金、銀、プラチナ
• 直近 90 日分の公開 USD マクロデータで評価できます。利用可能な全期間の履歴を利用するには、FXMacroData サブスクリプションに接続してください。
• get_fx_price で外国為替スポットレートの履歴を取得できます。
• USD 以外の指標、外国為替スポットレートの履歴、COT、商品などの保護されたデータセットには、認可済みの FXMacroData サブスクリプションのキーが必要です。
• 以下を完全にサポート：
  • 同期クライアント
  • 非同期クライアント
• 軽量：依存関係は requests と aiohttp のみです。

---

📦 インストール

PyPI からインストールします：

pip install fxmacrodata

または、GitHub から最新バージョンをインストールします：

pip install git+https://github.com/fxmacrodata/fxmacrodata.git

---

🔧 使い方

同期

from fxmacrodata import Client

client = Client(api_key="YOUR_API_KEY")

# Fetch macroeconomic indicators
data = client.get_indicator(
    "aud", "policy_rate",
    start_date="2023-01-01",
    end_date="2023-11-01"
)
print(data)

# Forex price endpoint
fx = client.get_fx_price("usd", "gbp", start_date="2025-01-01")
print(fx)

# Forex with technical indicators
fx = client.get_fx_price("eur", "usd", indicators="sma_20,rsi_14,macd")
print(fx)

# Release calendar
calendar = client.get_calendar("usd")
print(calendar)

# Data catalogue — discover available indicators
catalogue = client.get_data_catalogue("usd")
print(catalogue)

# COT positioning data
cot = client.get_cot("eur", start_date="2025-01-01")
print(cot)

# Commodity prices
gold = client.get_commodities("gold", start_date="2026-01-01")
print(gold)

---

非同期

import asyncio
from fxmacrodata import AsyncClient

async def main():
    async with AsyncClient(api_key="YOUR_API_KEY") as client:
        # Fetch macroeconomic indicators
        data = await client.get_indicator("eur", "inflation")
        print(data)

        # Forex price endpoint
        fx = await client.get_fx_price("usd", "jpy")
        print(fx)

        # Release calendar
        calendar = await client.get_calendar("usd")
        print(calendar)

        # Data catalogue
        catalogue = await client.get_data_catalogue("usd")
        print(catalogue)

        # COT positioning
        cot = await client.get_cot("jpy")
        print(cot)

        # Commodity prices
        gold = await client.get_commodities("gold")
        print(gold)

asyncio.run(main())

タイムアウトとエラー

すべてのリクエストには、デフォルトで 30 秒のタイムアウトが設定されています。クライアントごとに変更できます：

Client(api_key="YOUR_API_KEY", timeout=60)            # seconds
Client(api_key="YOUR_API_KEY", timeout=(3.05, 120))   # (connect, read)
AsyncClient(api_key="YOUR_API_KEY", timeout=60)       # total seconds

すべてのエラーは FXMacroDataError またはそのサブクラスです：

例外	発生条件
FXMacroDataAPIError	API が 200 以外のステータスを返した場合（.status_code が設定されます）。
FXMacroDataResponseError	API が 200 を返したものの、本文がエラーメッセージであるか、JSON オブジェクトではない場合。
FXMacroDataTimeoutError	リクエストがタイムアウト時間を超えた場合。
FXMacroDataTransportError	接続に失敗した場合（DNS、TLS、ネットワーク）。
FXMacroDataRedirectError	API キーが別のオリジンに送信されるリダイレクトは拒否されます。

API キーがエラーメッセージに含まれることはありません。また、API キーは設定したオリジンに HTTPS でのみ送信されます。別のホストや平文の HTTP へのリダイレクトは、キーを付けて追従するのではなく拒否されます。

---

OpenBB 連携

FXMacroData は、このパッケージから利用できる、実用的な OpenBB 連携方法すべてに対応しています。

• OpenBB Python：obb.fxmacrodata.* 用のインストール可能なプロバイダー／ルーター拡張機能です。
• OpenBB REST API：openbb-api 経由で /api/v1/fxmacrodata/* ルートを利用できます。
• OpenBB Workspace（自動生成）：インラインメタデータから openbb-api がウィジェットを生成します。
• OpenBB Workspace（カスタム）：widgets.json、apps.json、データエンドポイントを提供するスタンドアロンバックエンドです。
• OpenBB MCP：openbb-mcp 経由でツールを公開します。
• OpenBB CLI：openbb-build の実行後にコマンドを利用できます。

OpenBB パッケージには Python 3.10 以降が必要です。OpenBB Python の追加パッケージをインストールします。

pip install "fxmacrodata[openbb]"
openbb-build

次に、OpenBB Python インターフェースから FXMacroData を使用します。

from openbb import obb

obb.user.credentials.fxmacrodata_api_key = "YOUR_API_KEY"

catalogue = obb.fxmacrodata.data_catalogue(
    currency="USD",
    provider="fxmacrodata",
).to_df()

inflation = obb.fxmacrodata.macro_indicators(
    currency="USD",
    indicator="inflation",
    start_date="2020-01-01",
    provider="fxmacrodata",
).to_df()

eurusd = obb.fxmacrodata.fx_historical(
    base="EUR",
    quote="USD",
    start_date="2024-01-01",
    provider="fxmacrodata",
).to_df()

OpenBB REST API と、自動生成される Workspace バックエンドを起動します。

pip install "fxmacrodata[openbb-api]"
openbb-build
fxmacrodata-openbb-api --host 127.0.0.1 --port 6900

Workspace は http://127.0.0.1:6900 に接続できます。自動生成される /widgets.json は、FXMacroData のインライン OpenBB ウィジェットメタデータを使用します。

OpenBB Workspace のカスタムバックエンドを起動します。

pip install "fxmacrodata[workspace]"
fxmacrodata-openbb-backend

デフォルトのバックエンド URL：

http://127.0.0.1:7779

Workspace は /widgets.json、/apps.json、/catalogue、 /release_calendar、/macro_indicator、/forex、/cot、/commodity を公開します。 このバックエンドでは、Swagger／OpenAPI ドキュメントはデフォルトで無効になっています。ローカルでの デバッグ時のみ、起動前に FXMACRODATA_OPENBB_ENABLE_DOCS=1 を設定してください。

OpenBB MCP を起動します。

pip install "fxmacrodata[mcp]"
openbb-build
fxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001

OpenBB CLI を起動します。

pip install "fxmacrodata[openbb-cli]"
openbb-build
openbb

連携方法の一覧と、上流の OpenBB リポジトリへの個別のコントリビューション方法については、docs/openbb-integration.md を参照してください。

---

📘 API の概要

get_indicator(currency, indicator, start_date=None, end_date=None)

マクロ経済指標の時系列データを取得します。

• currency："usd"、"aud"、"eur"、"gbp"、"cad"、"nok"、"nzd"、"jpy"、"brl"、"cny"、"dkk"、"pln"、"sek"、"sgd" など。
• indicator："policy_rate"、"inflation"、"gdp"、"unemployment"、"trade_balance"、"current_account_balance"、"gov_bond_10y" など。
• USD 以外では API キーが必要です。

get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)

2 つの通貨間の日次 FX スポットレートを取得します。

• indicators：オプションのカンマ区切りテクニカル指標です。"sma_20"、"sma_50"、"sma_200"、"rsi_14"、"macd"、"ema_12"、"ema_26"、"bollinger_bands"、または "all" を指定できます。
• API キーが必要です。

get_calendar(currency, indicator=None)

通貨に関する今後の経済データ発表日を取得します。

• indicator：特定の指標スラッグで絞り込むためのオプション項目です。
• announcement_datetime（Unix タイムスタンプ）と release（指標スラッグ）を返します。

get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)

指定した通貨で利用可能なマクロ経済指標を検索します。

• 指標スラッグをキーとし、name、unit、frequency、has_official_forecast を含む辞書を返します。
• USD 以外では API キーが必要です。

get_cot(currency, start_date=None, end_date=None)

CFTC の Commitment of Traders（COT）ポジショニングデータを取得します。

• 対応通貨：AUD、CAD、CHF、EUR、GBP、JPY、NZD、USD。
• USD 以外では API キーが必要です。

get_commodities(indicator, start_date=None, end_date=None)

コモディティ価格の時系列データを取得します。

• indicator："gold"、"silver"、または "platinum"。
• API キーが必要です。

---

💹 対応通貨と指標

18 通貨に対応しています： AUD、BRL、CAD、CHF、CNH、CNY、DKK、EUR、GBP、ILS、JPY、NGN、NOK、NZD、PEN、SEK、THB、USD。

以下の表は、主要 4 通貨における指標の対応状況の一部を示しています。各通貨の全リストを確認するには、get_data_catalogue() を使用してください。

カテゴリ	指標	USD	EUR	AUD	GBP
経済	GDP 成長率	✓	✓	✓	✓
	インフレ率	✓	✓	✓	✓
	貿易収支	✓	✓	✓	✓
	経常収支	✓	✓	✓	✓
	小売売上高	✓	✓	✓	✓
	鉱工業生産	✓	—	—	—
労働市場	失業率	✓	✓	✓	✓
	雇用者数	✓	✓	✓	✓
	フルタイム雇用者数	✓	✓	✓	—
	パートタイム雇用者数	✓	✓	✓	✓
	労働参加率	✓	✓	✓	✓
	非農業部門雇用者数	✓	—	—	—
金融政策	政策金利	✓	✓	✓	✓
	無リスク金利	✓	✓	✓	✓
	中央銀行資産	✓	—	✓	—
国債利回り	2 年国債	✓	✓	✓	✓
	5 年国債	✓	✓	✓	✓
	10 年国債	✓	✓	✓	✓
	物価連動債	✓	✓	✓	✓

---

📄 ライセンス

MIT ライセンス © FXMacroData

---

🌐 リンク

• ウェブサイト：https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme
• API ドキュメント：https://fxmacrodata.com/docs?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme
• GitHub：https://github.com/fxmacrodata/fxmacrodata
• PyPI：https://pypi.org/project/fxmacrodata/
• Readthedocs：https://fxmacrodata.readthedocs.io/en/latest/
• Zenodo：https://zenodo.org/records/18280968