實物價格序列 API

探索美國燃油週度零售價格與世界銀行商品月度基準。

端點與請求

REST 端點

GET /v1/commodities/physical/series

介面契約請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series?commodity=gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

參數

名稱	必填	類型	含義
`commodity`	否	查詢 · 字串	依商品篩選，例如 gasoline、diesel、copper、urea、rice、crude-oil 或 coffee。請使用探索操作回傳的 commodity 值。
`category`	否	查詢 · 類別	支援的類別為 softs、oils-oilseeds、metals、grains、energy、fertilizers、forestry 與 livestock-dairy。燃油序列使用 energy。
`market`	否	查詢 · 市場代碼	全球基準使用 WLD，歐盟使用 EUU。支援的國家代碼為 USA、THA、JPN、AUS、ZAF、MYS、CMR、VNM、MEX、LKA、IND 與 KEN。美國燃油使用 USA。
`country`	否	查詢 · 市場代碼	取值與 market 相同，包括 WLD 與 EUU。如果 country 與 market 不同，則沒有符合的序列。
`price_type`	否	查詢 · 價格類型	燃油使用 retail_average。世界銀行序列使用 international_benchmark，但菸草使用 import_unit_value。
`currency`	否	查詢參數 · 貨幣代碼	依報價貨幣篩選。目前兩個來源均使用 USD。
`limit`	否	查詢·整數，1–500	每頁最多回傳的項目數，預設為100。
`cursor`	否	查詢 · 字串	使用上一頁的 next_cursor，並保持篩選條件與 limit 不變。null 表示沒有更多頁面。

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

回應

介面契約範例

{
  "series": [
    {
      "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"
    }
  ],
  "next_cursor": null
}

欄位	類型	必填	含義
`series`	陣列	是	序列包含商品、產品、市場、區域、價格基準、貨幣、單位、頻率、發布機構、來源署名與涵蓋日期。空陣列表示沒有符合的序列。
`series[].series_id`	字串	是	序列探索操作回傳的穩定 ID。
`series[].currency`	字串	是	報價貨幣。美國燃油與月度基準序列均使用 USD。
`series[].unit / series[].unit_quantity`	字串	是	發布時的單位與計價數量。燃油使用 us_gallon。月度基準使用 metric_ton、kilogram、barrel、cubic_meter、troy_ounce、mmbtu、dry_metric_ton_unit 或 sheet。數量為1，合板除外，其價格以每100張的 USD 金額計。數值不作換算。
`series[].attribution`	字串或 null	是	請隨資料保留回應中的來源署名。來源: 美國能源資訊署。來源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`series[].commodity / series[].category / series[].product`	字串	是	商品、類別與產品定義。例如 gasoline / energy / regular-gasoline 與 copper / metals / copper。探索操作會回傳各序列的對應值。
`series[].market / series[].area`	字串 / 字串或 null	是	計價市場與選填的區域範圍。WLD 表示全球基準，EUU 表示歐盟，國家市場使用 ISO alpha-3 代碼。美國燃油使用 USA，全美平均值的 area 為 null。
`series[].price_type / series[].basis`	字串 / 字串或 null	是	燃油使用 retail_average。月度序列使用 international_benchmark，但菸草使用 import_unit_value。basis 在資訊可用時說明價格定義。
`series[].frequency`	字串	是	美國燃油為 weekly，世界銀行基準為 monthly。
`series[].description / series[].publisher`	字串	是	序列定義與發布機構。
`series[].coverage_start / series[].coverage_end`	日期	是	最早觀測值的首日與最新觀測值的末日，包含這兩個日期。部分序列起始較晚或已結束。日期邊界不保證歷史資料連續且無缺口。
`next_cursor`	字串或 null	是	不需解析內部結構的續頁權杖。null 表示最後一頁。

錯誤與配額

400 invalid_query, 代碼、區域、日期範圍、limit 或選擇器無效。
400 invalid_cursor, 游標無效或與請求的篩選條件不符。
400 cursor_expired, 發布資料已變更。請不帶游標重新開始分頁查詢。
401 invalid_api_key, Bearer 金鑰缺漏或遭到拒絕。
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 金鑰即可存取。