實物價格序列詳情 API

讀取一個燃油週度序列或月度基準序列的定義、單位與涵蓋範圍。

端點與請求

REST 端點

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

介面契約請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-regular-gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_get_physical_series。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

回應

介面契約範例

{
  "series_id": "fuel-eia-usa-regular-gasoline",
  "commodity": "gasoline",
  "category": "energy",
  "product": "regular-gasoline",
  "market": "USA",
  "area": null,
  "price_type": "retail_average",
  "basis": "cash self-serve pump price incl. all taxes, 8:00 a.m. Monday",
  "currency": "USD",
  "unit": "us_gallon",
  "unit_quantity": "1",
  "frequency": "weekly",
  "description": "United States: regular gasoline (all formulations), weekly average retail price in dollars per gallon from EIA's Monday survey (series EMM_EPMR_PTE_NUS_DPG.W).",
  "publisher": "U.S. Energy Information Administration",
  "attribution": "Source: U.S. Energy Information Administration",
  "coverage_start": "2026-07-20",
  "coverage_end": "2026-10-05"
}

欄位	類型	必填	含義
`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
`commodity / category / product`	字串	是	商品、類別與產品定義。例如 gasoline / energy / regular-gasoline 與 copper / metals / copper。探索操作會回傳各序列的對應值。
`market / area`	字串 / 字串或 null	是	計價市場與選填的區域範圍。WLD 表示全球基準，EUU 表示歐盟，國家市場使用 ISO alpha-3 代碼。美國燃油使用 USA，全美平均值的 area 為 null。
`price_type / basis`	字串 / 字串或 null	是	燃油使用 retail_average。月度序列使用 international_benchmark，但菸草使用 import_unit_value。basis 在資訊可用時說明價格定義。
`frequency`	字串	是	美國燃油為 weekly，世界銀行基準為 monthly。
`description / publisher`	字串	是	序列定義與發布機構。
`coverage_start / coverage_end`	日期	是	最早觀測值的首日與最新觀測值的末日，包含這兩個日期。部分序列起始較晚或已結束。日期邊界不保證歷史資料連續且無缺口。

錯誤與配額

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 金鑰即可存取。