在 R 中使用 Narwhal API

用 R 和 Narwhal API，憑一把 API 金鑰拉取國定假日、發布日期、經濟資料、大宗商品現貨價格、匯率和預測市場賠率。把金鑰存放在 .Renviron 中，用 httr2 讀取回應，並在 R 腳本中使用回傳的欄位。

你將完成的設定

R 可以透過 httr2 呼叫 Narwhal REST API 並讀取 JSON 回應。你會得到一個可重複使用的 narwhal() 輔助函式、涵蓋全部六個資料領域的呼叫，以及一個可以排定為 pull.R 的腳本。輔助函式使用 https://api.narwhalapi.com 作為基礎 URL，並為每個請求加入路徑和查詢參數。Narwhal 的經濟資料包括 CPI、通膨、GDP 和殖利率；這裡的經濟資料呼叫挑選的是 CPI 觀測值。

範例把每個回應領域存放在各自的 R 物件中。國定假日和發布日期以記錄清單的形式回傳，CPI 觀測值、匯率和預測市場會議也是如此。大宗商品範例讀取單一的 price 欄位。為計算挑選欄位，或把記錄轉成資料框時，請記住這些回應的形狀。

設定你的 API 金鑰

  1. 建立免費金鑰 在 narwhalapi.com/signup 建立你的金鑰。Narwhal 用同一個帳號和同一把 API 金鑰涵蓋其各個資料 API。
  2. 把金鑰存放在 .Renviron 中 把金鑰放進 .Renviron，環境變數名稱為 NARWHAL_API_KEY。把預留位置換成你的金鑰，並且不要把金鑰寫進 pull.R。變數名稱必須與輔助函式中傳給 Sys.getenv() 的名稱一致。環境變數範例中的 ... 是金鑰的預留位置。
    環境變數
    NARWHAL_API_KEY=...
  3. 安裝 R 套件 用這裡的指令安裝 httr2 和 jsonlite。請求輔助函式使用 httr2 發出 GET 請求並讀取其 JSON 本文。
    安裝套件
    install.packages(c("httr2", "jsonlite"))

用程式碼取得資料

把這段程式碼儲存為 pull.R。輔助函式用 Sys.getenv() 讀取 NARWHAL_API_KEY，並透過 Authorization: Bearer YOUR_KEY 標頭把金鑰當作 Bearer 權杖傳送。每次呼叫提供一個路徑；需要日期範圍或貨幣選擇的呼叫還要提供查詢參數。後面的各領域範例都使用同一個輔助函式。

R，httr2 輔助函式和六個領域
library(httr2)

narwhal <- function(path, ...) {
  request("https://api.narwhalapi.com") |>
    req_url_path_append(path) |>
    req_url_query(...) |>
    req_auth_bearer_token(Sys.getenv("NARWHAL_API_KEY")) |>
    req_perform() |>
    resp_body_json()
}

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

cpi_values <- vapply(cpi, function(row) as.numeric(row$value), numeric(1))
n <- length(cpi_values)
mom <- cpi_values[n] / cpi_values[n - 1] - 1
print(round(mom * 100, 2))   # month-on-month change in percent

在輔助函式內部，req_url_path_append(path) 把端點路徑附加到基礎 URL，req_url_query(...) 加入查詢引數。req_auth_bearer_token() 接收從環境中讀取的金鑰。接著呼叫透過 req_perform() 和 resp_body_json() 把回應本文回傳給 R。如各領域範例所示，用 $ 從該本文中讀取指定名稱的欄位。

CPI 計算把每個觀測值的 value 讀取為數字。它用回傳清單中的最後一個值除以前一個值，再減去 1，並以百分比印出月增變化。在計算之外使用觀測值的數值時，period 欄位應與每個觀測值放在一起。

要把記錄清單轉成資料框，請使用 dplyr::bind_rows 或 do.call(rbind, lapply(x, as.data.frame))。這裡的 x 是你要轉換的清單，例如 holidays、releases 或 cpi。請先挑選回應欄位，讓轉換拿到的是該領域的記錄。

這些呼叫把路徑和查詢引數分開處理。對於 CPI，路徑選擇 USA CPI 觀測值，start 提供起始期間。對於匯率，路徑選擇 USD，currencies 提供 EUR 和 IDR。兩種呼叫都使用輔助函式的基礎 URL 和 Bearer 驗證。

排定每日拉取

用 cron 或 Windows Task Scheduler 每天執行一次 Rscript pull.R。cronR 套件可以幫你寫出 cron 行。把你需要的請求連同輔助函式及其環境變數讀取一起保留在 pull.R 中，這樣排程指令呼叫的就是同一個腳本。

每日腳本指令
Rscript pull.R

日期和貨幣選擇仍維持腳本中寫的樣子。例如，發布日期呼叫請求的是 2026 年 11 月，國定假日呼叫請求的是 2026 年的 USA 國定假日。每日排程會重複這些請求。排程方式請參閱排程每日資料拉取。

R 中的國定假日

從 holidays 讀取 2026 年 USA 的國定假日。每筆記錄都有 date 和 name，所以把記錄轉成資料框時請同時保留這兩個欄位。這次呼叫在路徑中使用國家和年份，並從回應中讀取國定假日清單。

讀取國定假日
response <- narwhal("v1/calendars/holidays/USA/2026")
holidays <- response$holidays
holidays

R 中的發布日期

從 releases 讀取 2026 年 11 月 USA 的經濟發布日期。請求包含國家、開始日期、結束日期和數量上限。每個發布都有 at、period、topic 和 status；在 R 中使用發布記錄時，請把這些欄位放在一起。

讀取發布日期
response <- narwhal("v1/economics/calendar", countries = "USA",
                    start_date = "2026-11-01", end_date = "2026-11-30", limit = 100)
releases <- response$releases
releases

R 中的經濟資料

從 observations 讀取起始期間為 2025 年 9 月的 USA CPI 觀測值。每個觀測值都有 period 和 value。輔助函式範例用這些數值計算月增變化；呈現觀測值或由它得出的結果時，請讓期間與數值放在一起。

讀取 CPI 觀測值
response <- narwhal("v1/economics/USA/cpi/observations", start = "2025-09")
cpi <- response$observations
cpi

R 中的大宗商品現貨價格

從 price 讀取以 USD 計價的 Brent 現貨價格。這次呼叫在路徑中選擇商品和貨幣，然後用 as.numeric() 轉換回傳的價格。大宗商品現貨代碼包括 XAU、XAG、XPT、XPD、XCU、BRENT 和 WTI 等。

讀取 Brent 現貨價格
response <- narwhal("v1/commodities/spot/BRENT/USD")
brent <- as.numeric(response$price)
brent

R 中的匯率

以 USD 為基準貨幣，讀取所請求貨幣 EUR 和 IDR 的匯率。回應欄位是 rates，每筆記錄都有 currency 和 rate。把清單轉成資料框時，請讓貨幣欄位與其匯率放在一起。

讀取匯率
response <- narwhal("v1/fx/rates/USD", currencies = "EUR,IDR")
fx <- response$rates
fx

R 中的預測市場賠率

從 meetings 讀取美國聯準會政策利率路徑的回應。每次會議都有 resolves_at、p_cut、p_hold 和 p_hike。把機率讀入 R 時，請把會議欄位放在一起，讓結算時間與降息、維持和升息欄位並列。

讀取政策路徑會議
response <- narwhal("v1/predictions/policy-paths/federal-reserve")
fed <- response$meetings
fed

金鑰應該放在哪裡？

把金鑰放在 .Renviron 中，絕不要寫進腳本。輔助函式讀取 Sys.getenv("NARWHAL_API_KEY") 用於 Bearer 驗證。REST 和 MCP 共用這把金鑰，所以無論透過哪種方式存取 Narwhal，你用的都是同一個帳號和金鑰。

為什麼 price 是字串？

十進位數以字串形式回傳。如 Brent 範例所示，請用 as.numeric() 把 price 轉成數字，以便在 R 中計算。CPI 計算也會先轉換每個觀測值的 value，再相除以得到變化。

發布於 。

後續步驟