最新實物價格 API

讀取最新可用的燃油週度價格或月度基準價格及其觀測期間。

端點與請求

REST 端點

GET /v1/commodities/physical/series/{series_id}/latest

介面契約請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/latest" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_get_physical_latest。REST 和 MCP 共用相同的結構描述、帳戶配額、授權檢查與問題格式。

參數

名稱	必填	類型	含義
`series_id`	是	路徑 · 字串	請使用探索操作回傳的穩定 ID，例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。

來源: 美國能源資訊署。來源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

回應

介面契約範例

{
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "price": "14474",
  "published_on": null,
  "revision": 1,
  "series_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)"
}

欄位	類型	必填	含義
`series_id`	字串	是	序列探索操作回傳的穩定 ID。
`currency`	字串	是	報價貨幣。美國燃油與月度基準序列均使用 USD。
`unit / unit_quantity`	字串	是	發布時的單位與計價數量。燃油使用 us_gallon。月度基準使用 metric_ton、kilogram、barrel、cubic_meter、troy_ounce、mmbtu、dry_metric_ton_unit 或 sheet。數量為1，合板除外，其價格以每100張的 USD 金額計。數值不作換算。
`attribution`	字串或 null	是	請隨資料保留回應中的來源署名。來源: 美國能源資訊署。來源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`period_start / period_end`	日期	是	觀測日期，包含起訖日期。燃油的兩個日期均為週一調查日期。月度觀測值涵蓋整個月，例如2026-09-01至2026-09-30。
`price`	十進位數值字串	是	以序列貨幣發布的價格，每 unit_quantity 個單位計價。請搭配序列的價格類型與 basis 解讀。
`published_on`	日期或 null	是	發布日期（如有）。日期未知時保留 null。
`revision`	整數	是	從1開始，後續發布修改該期間的數值時遞增。

錯誤與配額

400 invalid_query, 代碼、區域、日期範圍、limit 或選擇器無效。
401 invalid_api_key, Bearer 金鑰缺漏或遭到拒絕。
404 physical_series_not_found, 沒有完整且已核准的資料符合請求。
429 rate_limit_exceeded 或 quota_exhausted, 共用配額已用盡。
503 physical_reference_unavailable, 無法取得完整的發布資料。

遭拒的請求和伺服器錯誤不會消耗每月配額。

涵蓋範圍

提供20個美國燃油零售價格週度序列，涵蓋普通汽油與2號公路用柴油，各自包含全美平均值與九個地區。價格以 USD/美制加侖計。歷史始於2026年7月20日，並在每週一調查後逐週增加。來源: 美國能源資訊署。月度資料涵蓋世界銀行的70個序列，包括軟性商品、油脂與油籽、金屬、穀物、能源、肥料、林產品以及畜牧與乳製品。歷史最早可追溯至1960年，部分序列起始較晚。最新可用月份為2026年9月，但個別序列可能落後或已結束。大麥與高粱資料截至2020年8月，墨西哥蝦資料截至2023年10月。請查看各序列的 coverage_end。所有價格均以 USD 計價，並保留發布時的單位。來源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

使用 Narwhal API 金鑰即可存取。