實物價格歷史 API

讀取燃油週度價格或商品月度價格歷史，包括期間、發布時的單位與修訂資訊。

端點與請求

REST 端點

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

介面契約請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/observations?start=2026-07-01&end=2026-10-01&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

參數

名稱	必填	類型	含義
`series_id`	是	路徑 · 字串	請使用探索操作回傳的穩定 ID，例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。
`start`	否	查詢·YYYY-MM-DD	包含起始日期。請同時提供 start 與 end，或同時省略兩者。
`end`	否	查詢·YYYY-MM-DD	結束日期不包含在內，且必須晚於 start。回傳與該日期區間重疊的觀測值。
`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_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)",
  "observations": [
    {
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "price": "13543",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "price": "14326",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "price": "14474",
      "published_on": null,
      "revision": 1
    }
  ],
  "next_cursor": null
}

欄位	類型	必填	含義
`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
`observations`	陣列	是	觀測值按由舊到新排序。每項包含 period_start、period_end、以十進位字串表示的 price、可為 null 的 published_on 與 revision。
`observations[].period_start / observations[].period_end`	日期	是	觀測日期，包含起訖日期。燃油的兩個日期均為週一調查日期。月度觀測值涵蓋整個月，例如2026-09-01至2026-09-30。
`observations[].price`	十進位數值字串	是	以序列貨幣發布的價格，每 unit_quantity 個單位計價。請搭配序列的價格類型與 basis 解讀。
`observations[].published_on`	日期或 null	是	發布日期（如有）。日期未知時保留 null。
`observations[].revision`	整數	是	從1開始，後續發布修改該期間的數值時遞增。
`next_cursor`	字串或 null	是	不需解析內部結構的續頁權杖。null 表示最後一頁。

錯誤與配額

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