Jupyter API と pandas で Narwhal API を使う

セットアップする内容

Jupyter は、この pandas のワークフローで使うノートブックです。最終的に、リクエストヘルパー、返されたレコードの DataFrame、数値の Brent スポット価格が手に入ります。Narwhal は1つのアカウントと1つの APIキーでデータ API 全体を利用でき、REST と MCP でも同じキーを共有します。ノートブックは https://api.narwhalapi.com への REST リクエストを使い、キーは Authorization: Bearer YOUR_KEY ヘッダーに入れます。経済データ API には CPI、インフレ、GDP、利回りが含まれ、このノートブックでは CPI の観測値を使って前月比を計算します。

APIキーを設定

1. 無料キーを作成する Narwhal のサインアップで無料のキーを取得します。そのキーを、ノートブックのすべてのデータ分野のリクエストに使います。
2. ノートブックのパッケージをインストールする ノートブックを開く前に、pandas、requests、Jupyter をインストールします。コードは HTTP 呼び出しに requests、返されたレコードの処理に pandas を使います。
   パッケージをインストールする

   pip install pandas requests jupyter

3. キーを設定して Jupyter を起動する YOUR_KEY を自分のキーに置き換え、Jupyter Lab を起動する前に NARWHAL_API_KEY をエクスポートします。保存するノートブックのセルには、キーを書き込まないでください。Python のコードは環境変数から読み取ります。セルの os.environ による参照は、ベアラーヘッダーを組み立てるときにこの変数名をそのまま使います。
   キーを渡して Jupyter を起動する

   export NARWHAL_API_KEY=YOUR_KEY
   jupyter lab

コードでデータを取得する

この Python コードをノートブックに入れます。pd.read_json(url) は認証ヘッダーを送れないため、get ヘルパーが requests でリクエストして JSON を返します。各 DataFrame は、その分野のレスポンスのフィールドを使います。CPI の計算は、返されたレベルから前月比を求め、予測の日付は pd.to_datetime で変換します。ヘルパーはクエリパラメーターを params で渡し、呼び出しごとに HEADERS を送り、timeout=10 を設定します。JSON のレスポンスを読む前に raise_for_status() を呼び出します。各リクエストで同じ認証処理を使えるよう、このヘルパーは各分野の呼び出しと一緒に置いてください。

import os
import pandas as pd
import requests

API = "https://api.narwhalapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}


def get(path, **params):
    r = requests.get(API + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


holidays = pd.DataFrame(get("/v1/calendars/holidays/USA/2026")["holidays"])
releases = pd.DataFrame(
    get(
        "/v1/economics/calendar",
        countries="USA",
        start_date="2026-11-01",
        end_date="2026-11-30",
        limit=100,
    )["releases"]
)
cpi = pd.DataFrame(
    get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
)
fx = pd.DataFrame(get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"])
fed = pd.DataFrame(get("/v1/predictions/policy-paths/federal-reserve")["meetings"])
brent = float(get("/v1/commodities/spot/BRENT/USD")["price"])

cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date

print(holidays[["date", "name"]].head(3))
print(cpi[["period", "value", "mom_pct"]].tail(3))
print(fx)
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))
print("Brent", brent)

2026年10月24日時点で、直近3件の CPI の行は、2026年7月が 333.918 で前月比 -0.01%、2026年8月が 334.980 で 0.32%、2026年9月が 336.940 で 0.59% でした。mom_pct 列は、CPI のレベルから pct_change() * 100 で計算します。

スケジュールで実行する

jupyter nbconvert でノートブックをスクリプトに変換し、そのスクリプトを cron から実行します。スケジュール実行するスクリプトでも、キーは NARWHAL_API_KEY に保存します。HEADERS の代入はノートブックと同じ環境変数を読み取ります。変換コマンドでは、ノートブックのファイル名に pull.ipynb を使います。

jupyter nbconvert --to script pull.ipynb

同じ関数を、スケジュールされたジョブから呼び出すこともできます。そのジョブには、ノートブックのリクエストヘルパーと各分野の呼び出しを使い、ベアラーヘッダーは HEADERS で渡します。取得のスケジュールについては、毎日のデータ取得をスケジュールするを参照してください。

pandas で祝日を扱う

2026年の米国の祝日を holidays レスポンスフィールドから読み取ります。各祝日には date と name があるため、ノートブックではこれらの列で祝日の日付と名前を並べて表示できます。このサンプルは、全体のセルと同じ認証付きの get ヘルパーを使い、表示用にそれらのフィールドを選択します。エリアごとのサンプルを使う前に、ヘルパーを定義しておいてください。

data = get("/v1/calendars/holidays/USA/2026")
holidays = pd.DataFrame(data["holidays"])
print(holidays[["date", "name"]].head(3))

pandas で発表日を扱う

経済カレンダーから、2026年11月1日から2026年11月30日までの米国の発表データを limit=100 で取得します。レスポンスのフィールドは releases で、各レコードには at、period、topic、status があり、DataFrame にまとめて表示できます。発表日にはこの呼び出しを使い、期間ごとの CPI レベルには経済データのサンプルにある観測値の呼び出しを使います。

data = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)
releases = pd.DataFrame(data["releases"])
print(releases[["at", "period", "topic", "status"]])

pandas で経済データを扱う

start=2025-09を付けてUSAのCPI観測値をリクエストし、observationsをDataFrameに読み込みます。各レコードにはperiodとvalueがあります。前月比を計算する前に、value列を変換してください。

data = get("/v1/economics/USA/cpi/observations", start="2025-09")
cpi = pd.DataFrame(data["observations"])
cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
print(cpi[["period", "value", "mom_pct"]].tail(3))

pandas でコモディティのスポット価格を扱う

Brent の呼び出しは price フィールドを読み取り、float に変換します。スポットコードに BRENT、リクエストパスに USD を使います。スポットコードには、たとえば XAU、XAG、XPT、XPD、XCU、BRENT、WTI があります。このサンプルでは Brent のパスをそのまま使い、float が返す数値をノートブックで使ってください。

data = get("/v1/commodities/spot/BRENT/USD")
brent = float(data["price"])
print("Brent", brent)

pandas で為替レートを扱う

このサンプルの為替レートは、USD のレートのパスに currencies=EUR,IDR を付けてリクエストします。rates フィールドを DataFrame に読み込むと、返された各レコードに currency と rate があります。それらの列を選択すれば、通貨をレートの隣に保てます。このリクエストは、CPI や祝日の呼び出しと同じキーとヘッダーを使います。

data = get("/v1/fx/rates/USD", currencies="EUR,IDR")
fx = pd.DataFrame(data["rates"])
print(fx[["currency", "rate"]])

pandas で予測市場のオッズを扱う

連邦準備制度の政策パスを meetings フィールドから読み取ります。各会合には resolves_at、p_cut、p_hold、p_hike があります。全体のセルと同じ pandas の式で resolves_at を日付に変換し、確率のフィールドと並べて表示します。これにより、会合の決定日と、利下げ、ホールド、利上げの各フィールドがノートブックの出力にまとまります。

data = get("/v1/predictions/policy-paths/federal-reserve")
fed = pd.DataFrame(data["meetings"])
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))

数値が文字列になっているのはなぜですか?

API は精度を保つため、小数を文字列で返します。数値計算が必要なときは、DataFrame の列に astype(float) を使います。たとえば cpi["value"].astype(float) のようにします。単一の Brent 価格では、サンプルは返された price フィールドに float を使っています。変換は算術に必要な値にだけ適用してください。数値になっても、レスポンスのフィールド名は変わりません。

前年比はどうやって求めますか?

総合の変化率は/v1/economics/USA/inflationを呼び出して取得します。year_over_yearとmonth_over_monthが返されます。CPIの水準から前年比を計算するには、比較する月の12か月前の水準が必要なので、少なくとも13か月分の水準をリクエストしてください。