在 Python 中使用 Narwhal API

你可以用 Python 和 Narwhal，憑一把 API 金鑰拉取國定假日、發布日期、經濟資料、大宗商品現貨價格、匯率和預測市場賠率。用 requests 讀取 JSON 回應，再用 cron 為腳本排定每日拉取。

你將完成的設定

安裝了 requests 的 Python 3 可以讓你寫出一個呼叫 Narwhal REST API 的腳本，並讀取每個資料領域的回應欄位。你會得到一個共用的請求輔助函式、每個領域的範例，以及一條每日 cron 項目。Narwhal 用同一個帳號和同一把 API 金鑰涵蓋其各個資料 API；REST 和 MCP 共用這把金鑰。範例使用 https://api.narwhalapi.com 作為基礎 URL，並傳送 Authorization: Bearer YOUR_KEY。路徑用來選擇資料領域，每次呼叫從 JSON 回應中讀取對應的欄位。

設定你的 API 金鑰

  1. 建立免費金鑰 在 narwhalapi.com/signup 建立你的免費金鑰。每個請求的 Authorization 標頭都使用同一把金鑰，所以整個腳本都可以用它。
  2. 把金鑰存放在 shell 環境中 在你要使用 curl 和 Python 的 shell 中設定 NARWHAL_API_KEY，並把預留位置換成你的金鑰。Python 輔助函式在建立 Bearer 標頭時讀取這個環境變數。
    API 金鑰
    export NARWHAL_API_KEY=...
  3. 為 Python 3 安裝 requests 為 Python 腳本安裝 requests。PyPI 上還有 narwhalapi SDK，可用 pip install narwhalapi 安裝。
    安裝 requests
    pip install requests

撰寫 Python 之前先拉取資料

  1. 請求國定假日 JSON 使用 curl 和你在 shell 中設定的環境變數。這個請求會向國定假日端點傳送 Bearer 標頭，並在你撰寫 Python 程式碼之前印出 JSON。
    國定假日請求
    curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/USA/2026"
  2. 讀取國定假日資料列 在 holidays 中查看回傳的資料列。每一列都有 date 和 name；Python 範例先計算列數，然後用這些欄位印出第一個國定假日。

用程式碼取得資料

六個請求都使用共用的 get 輔助函式。它把 API 基礎 URL 與路徑串接，傳送標頭，傳遞查詢參數，並在 raise_for_status() 之後讀取 JSON。隨後各次呼叫挑選每個領域的回應欄位，因此 print 陳述式可以處理國定假日資料列、發布日期、觀測值、現貨價格、匯率和會議機率。

查詢參數留在各自的呼叫中：發布日期請求包含國家、日期邊界和數量上限，而匯率請求包含貨幣。輔助函式透過 params 傳送它們，然後回傳解析後的回應。請把輔助函式放在各領域範例之前，這樣每個範例都能使用 get、API 和 HEADERS。下面的每個範例都用自己的路徑和回應欄位重複使用這個輔助函式。

Python，全部六個領域
import os
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 = get("/v1/calendars/holidays/USA/2026")["holidays"]
releases = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)["releases"]
cpi = get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
brent = get("/v1/commodities/spot/BRENT/USD")["price"]
fx = get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"]
fed = get("/v1/predictions/policy-paths/federal-reserve")["meetings"]

print(len(holidays), holidays[0]["date"], holidays[0]["name"])
print(len(releases), releases[0]["period"], releases[0].get("at"))
print(cpi[-1]["period"], cpi[-1]["value"])
print("Brent", brent)
print({r["currency"]: r["rate"] for r in fx})
print(fed[0]["resolves_at"][:10], fed[0]["p_hold"])

按排程定時執行

可以用一條 cron 項目每天執行一次腳本。使用提供的項目，並把腳本放在 /path/pull.py；它呼叫 /usr/bin/python3，並把印出的輸出附加到 pull.log。腳本每天發出六次呼叫，請求數量很少。

每日 cron 項目
0 7 * * * /usr/bin/python3 /path/pull.py >> pull.log

在工作執行的環境中設定 NARWHAL_API_KEY。在共用機器上，請把金鑰放在工作會載入的檔案中，不要寫進 crontab。排程腳本讀取的變數與 shell 範例相同，請求也使用同樣的 Bearer 標頭。

Python 中的國定假日

讀取 holidays 取得每個國定假日的日期和名稱。2026 年 10 月 24 日的回應包含 2026 年的 11 個 US 國定假日，1 月 1 日的元旦排在第一位。這個範例使用共用的輔助函式，並從第一列印出這兩個欄位；完整腳本還會印出國定假日資料列的數量。

國定假日日期和名稱
holidays = get(
    "/v1/calendars/holidays/USA/2026"
)["holidays"]
print(holidays[0]["date"], holidays[0]["name"])

Python 中的發布日期

讀取 releases 取得所請求國家和日期範圍內的經濟發布日期。每個發布都有 at、period、topic 和 status。2026 年 10 月 24 日的回應在 2026 年 11 月的範圍內包含 31 個發布。範例印出第一個發布的 period，並像完整腳本一樣用 .get() 讀取它的 at 欄位。

經濟資料發布日期
releases = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)["releases"]
print(releases[0]["period"], releases[0].get("at"))

Python 中的經濟資料

讀取 observations 取得 CPI 的期間和數值，用 start 請求從某個期間開始的觀測值。在 2026 年 10 月 24 日的回應中，2026 年 9 月的 CPI 指數為 336.940。每個觀測值都有 period 和 value；這個範例從回傳的最後一列讀取這兩個欄位。Narwhal 的經濟資料還包括通膨、GDP 和殖利率。

CPI 觀測值
cpi = get(
    "/v1/economics/USA/cpi/observations", start="2025-09"
)["observations"]
print(cpi[-1]["period"], cpi[-1]["value"])

Python 中的大宗商品現貨價格

讀取 price 取得以 USD 計價的 Brent 現貨價格。2026 年 10 月 24 日的回應顯示 Brent 為每桶 116.8809 美元。範例把這個欄位指派給 brent，並帶標籤印出來。大宗商品現貨代碼包括 XAU、XAG、XPT、XPD、XCU、BRENT 和 WTI 等；這個請求使用 BRENT。

Brent 現貨價格
brent = get(
    "/v1/commodities/spot/BRENT/USD"
)["price"]
print("Brent", brent)

Python 中的匯率

讀取 rates 取得所請求貨幣對 USD 的匯率。每一列都有 currency 和 rate，範例把它們轉成字典。2026 年 10 月 24 日的回應顯示 USD/EUR 為 0.89342，USD/IDR 為 18107.8，均為 2026 年 10 月 23 日的收盤價。這次呼叫透過 currencies 參數同時請求 EUR 和 IDR。

USD 匯率
fx = get(
    "/v1/fx/rates/USD", currencies="EUR,IDR"
)["rates"]
print({r["currency"]: r["rate"] for r in fx})

Python 中的預測市場賠率

讀取 meetings 取得美國聯準會政策利率路徑。每次會議都有 resolves_at、p_cut、p_hold 和 p_hike。2026 年 10 月 24 日的回應顯示，2026 年 10 月 28 日會議的維持不變機率為 0.9188。這個範例使用與完整腳本相同的欄位，印出 resolves_at 的日期部分和第一次會議的 p_hold 值。

美國聯準會會議機率
fed = get(
    "/v1/predictions/policy-paths/federal-reserve"
)["meetings"]
print(fed[0]["resolves_at"][:10], fed[0]["p_hold"])

為什麼會得到 401？

Authorization 標頭遺失，或是環境變數為空。用 bool(os.environ.get('NARWHAL_API_KEY')) 印出 Python 是否拿到了 NARWHAL_API_KEY 的值。輔助函式用這個變數建立標頭，所以要在腳本執行的環境中設定它。預期的標頭是 Authorization: Bearer YOUR_KEY，金鑰值由環境變數提供。對於排程拉取，請在工作環境中檢查變數是否為空。

如何把資料列清單轉成表格？

對你想轉成表格的資料列清單使用 pandas.DataFrame(rows)。國定假日呼叫的清單是 holidays；發布日期的清單是 releases。讀取回應資料列之後如何處理表格，請參閱 pandas 教學。CPI 的 observations、匯率的 rates 和預測的 meetings 欄位同樣是資料列清單。在傳給 pandas.DataFrame(rows) 之前，先在 Python 中挑選回應欄位。

發布於 。

後續步驟