用 pandas API 資料串接 Jupyter 使用 Narwhal API

你將完成的設定

Jupyter 是這個 pandas 工作流程所用的筆記本。最終你會得到一個請求輔助函式、裝有回傳記錄的 DataFrame，以及數值形式的 Brent 現貨價格。Narwhal 以一個帳號、一把 API 金鑰涵蓋所有資料 API，REST 與 MCP 共用該金鑰。筆記本透過 REST 向 https://api.narwhalapi.com 發出請求，金鑰放在 Authorization: Bearer YOUR_KEY 標頭中。經濟數據 API 包括 CPI、通膨、GDP 和殖利率；這個筆記本用 CPI 觀測值計算月增率。

設定你的 API 金鑰

1. 建立免費金鑰 在 Narwhal 註冊頁取得免費金鑰，並把它用於筆記本中各個資料領域的請求。
2. 安裝筆記本所需的套件 開啟筆記本之前，先安裝 pandas、requests 和 Jupyter。程式碼用 requests 發出 HTTP 呼叫，用 pandas 處理回傳的記錄。
   安裝套件

   pip install pandas requests jupyter

3. 設定金鑰並啟動 Jupyter 把 YOUR_KEY 換成你的金鑰，並在啟動 Jupyter Lab 之前匯出 NARWHAL_API_KEY。不要把金鑰寫進會儲存的筆記本儲存格；Python 程式碼從環境變數讀取。儲存格裡的 os.environ 查找在建立 Bearer 標頭時使用的正是這個變數名稱。
   帶著金鑰啟動 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 日，最近三列 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 提供 Bearer 標頭。有關排定擷取，請見排定每日資料擷取。

在 pandas 中使用國定假日

從 holidays 回應欄位讀取 2026 年美國國定假日。每個假日都有 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 個月的水準值。