所有 API

美國燃料價格 API

油價 API 提供 1990 年起的汽油歷史價格與 1994 年起的柴油價格,每週更新,單位為美元每美制加侖。資料來源:美國能源資訊署(EIA)。

在線99.96% uptime, last 30天357 ms 一般回應

首次請求

尋找美國汽油序列

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series?commodity=gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
回應範例
{
  "series": [
    {
      "series_id": "fuel-eia-usa-regular-gasoline",
      "commodity": "gasoline",
      "category": "energy",
      "product": "regular-gasoline",
      "country": "USA",
      "price_type": "retail_average",
      "basis": "cash self-serve pump price incl. all taxes, 8:00 a.m. Monday",
      "currency": "USD",
      "unit": "us_gallon",
      "unit_key": "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).",
      "attribution": "Source: U.S. Energy Information Administration",
      "coverage_start": "1990-08-20",
      "coverage_end": "2026-10-19"
    }
  ],
  "next_cursor": null
}

端點

GET探索實物價格序列/v1/commodities/physical/series

探索每週美國零售燃料價格、每日石油與天然氣現貨價格,以及每月商品基準價格。

參數

  • commodity選填

    依商品篩選,例如 gasoline、diesel、copper、urea、rice、crude-oil 或 coffee。請使用探索操作回傳的 commodity 值。

  • category選填

    支援的類別為 softs、oils-oilseeds、metals、grains、energy、fertilizers、forestry 與 livestock-dairy。燃油序列使用 energy。

  • country選填

    全球基準使用 WLD,歐盟使用 EUU。支援的國家代碼為 USA、THA、JPN、AUS、ZAF、MYS、CMR、VNM、MEX、LKA、IND 與 KEN。美國燃油使用 USA。

  • price_type選填

    燃料使用retail_average。EIA每日現貨和World Bank序列使用international_benchmark,菸草除外,使用import_unit_value。

  • currency選填

    依報價貨幣篩選。目前兩個來源均使用 USD。

  • limit選填

    每頁最多回傳的項目數,預設為100。

  • cursor選填

    使用上一頁的 next_cursor,並保持篩選條件與 limit 不變。null 表示沒有更多頁面。

回應欄位

  • series陣列

    序列包含 commodity、product、country、area、價格基準 basis、currency、unit、frequency、attribution 與涵蓋日期。空陣列表示沒有符合的序列。

  • 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[].unit_key字串

    unit_key 是以一種標準寫法表示的單位,例如 troy_ounce、barrel 或 tonne;unit 則保留來源的原始寫法。當價格以美分報價時,price_scale 為 0.01:將價格乘以該值即可得到以貨幣計的金額。

  • series[].attribution字串

    請隨資料保留回應中的來源署名。來源: 美國能源資訊署。來源: 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[].commodity_key字串

    commodity_key 在現貨、期貨、預測與實物價格中以相同方式命名商品,例如 gold 或 crude-oil。原油另有 benchmark(wti、brent、urals 或 dubai),期貨則有 exchange_mic,即交易所的標準代碼。

  • series[].area字串

    area 表示地區範圍,全國序列省略此欄位。

  • series[].country字串

    WLD 表示世界基準。EUU 表示歐盟。國家使用 ISO alpha-3 代碼。美國燃油全國平均值使用 USA。

  • series[].price_type字串

    燃料使用retail_average。EIA每日現貨和月度序列使用international_benchmark,菸草除外,使用import_unit_value。

  • series[].basis字串

    basis 說明價格定義,來源未提供時省略。


完整參考文件 →
GET取得實物價格序列詳情/v1/commodities/physical/series/{series_id}

讀取單一每週燃料或每月基準價格序列的定義、單位與涵蓋範圍。

參數

  • series_id必填

    請使用探索操作回傳的穩定 ID,例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。

回應欄位

  • 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 金額計。數值不作換算。

  • unit_key字串

    unit_key 是以一種標準寫法表示的單位,例如 troy_ounce、barrel 或 tonne;unit 則保留來源的原始寫法。當價格以美分報價時,price_scale 為 0.01:將價格乘以該值即可得到以貨幣計的金額。

  • attribution字串

    請隨資料保留回應中的來源署名。來源: 美國能源資訊署。來源: 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。探索操作會回傳各序列的對應值。

  • commodity_key字串

    commodity_key 在現貨、期貨、預測與實物價格中以相同方式命名商品,例如 gold 或 crude-oil。原油另有 benchmark(wti、brent、urals 或 dubai),期貨則有 exchange_mic,即交易所的標準代碼。

  • area字串

    area 表示地區範圍,全國序列省略此欄位。

  • country字串

    WLD 表示世界基準。EUU 表示歐盟。國家使用 ISO alpha-3 代碼。美國燃油全國平均值使用 USA。

  • price_type字串

    燃料使用retail_average。EIA每日現貨和月度序列使用international_benchmark,菸草除外,使用import_unit_value。

  • basis字串

    basis 說明價格定義,來源未提供時省略。

  • frequency字串

    EIA石油和天然氣現貨價格為每日資料,美國燃料為每週資料,World Bank基準價格為每月資料。


完整參考文件 →
GET取得最新實物價格/v1/commodities/physical/series/{series_id}/latest

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

參數

  • series_id必填

    請使用探索操作回傳的穩定 ID,例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。

回應欄位

  • 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 金額計。數值不作換算。

  • unit_key字串

    unit_key 是以一種標準寫法表示的單位,例如 troy_ounce、barrel 或 tonne;unit 則保留來源的原始寫法。當價格以美分報價時,price_scale 為 0.01:將價格乘以該值即可得到以貨幣計的金額。

  • attribution字串

    請隨資料保留回應中的來源署名。來源: 美國能源資訊署。來源: 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日期

    發布日期。來源未提供時省略。

  • revision整數

    從1開始,後續發布修改該期間的數值時遞增。


完整參考文件 →
GET取得實物價格歷史/v1/commodities/physical/series/{series_id}/observations

讀取每週燃料或每月商品價格歷史,包含期間、公布單位與修訂紀錄。

參數

  • series_id必填

    請使用探索操作回傳的穩定 ID,例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。

  • start選填

    包含起始日期。請同時提供 start 與 end,或同時省略兩者。

  • end選填

    結束日期不包含在內,且必須晚於 start。回傳與該日期區間重疊的觀測值。

  • limit選填

    每頁最多回傳的項目數,預設為100。

  • cursor選填

    使用上一頁的 next_cursor,並保持篩選條件與 limit 不變。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 金額計。數值不作換算。

  • unit_key字串

    unit_key 是以一種標準寫法表示的單位,例如 troy_ounce、barrel 或 tonne;unit 則保留來源的原始寫法。當價格以美分報價時,price_scale 為 0.01:將價格乘以該值即可得到以貨幣計的金額。

  • attribution字串

    請隨資料保留回應中的來源署名。來源: 美國能源資訊署。來源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

  • observations陣列

    觀測值按由舊到新排序。每項包含 period_start、period_end、以十進位字串表示的 price 與 revision。published_on 為選填欄位。

  • observations[].period_start / observations[].period_end日期

    觀測日期,包含起訖日期。燃油的兩個日期均為週一調查日期。月度觀測值涵蓋整個月,例如2026-09-01至2026-09-30。

  • observations[].price十進位數值字串

    以序列貨幣發布的價格,每 unit_quantity 個單位計價。請搭配序列的價格類型與 basis 解讀。

  • observations[].published_on日期

    發布日期。來源未提供時省略。

  • observations[].revision整數

    從1開始,後續發布修改該期間的數值時遞增。

  • next_cursor字串或 null

    不需解析內部結構的續頁權杖。null 表示最後一頁。


完整參考文件 →

使用情境

以你的貨幣顯示價格

用匯率把商品價格換算成你自己的貨幣。

閱讀指南 →

回補完整歷史

分頁讀取全部歷史,儲存到檔案,中斷後可繼續。

閱讀指南 →

每日資料拉取

每天執行一次小腳本,把結果附加到 CSV 檔案。

閱讀指南 →

涵蓋範圍

來源

相關 API

棕櫚油價格 API

印尼與馬來西亞的毛棕櫚油與新鮮果串價格。

探索 API →

歷史商品價格 API

來自世界銀行 Pink Sheet 的 70 個月度序列。

探索 API →

實物大宗商品價格 API

棕櫚油、每日石油和天然氣價格、美國每週零售燃料價格以及月度商品基準價,單位與發布時一致。

探索 API →

現貨金屬價格 API

黃金、白銀、鉑金和鈀金的現貨價格,以及 WTI、布蘭特和銅的參考價格。

探索 API →

價格

每月 10 美元免費額度,之後每 1,000 次呼叫 2 美元起。

查看價格 →

常見問題

汽油價格 API 涵蓋哪些內容?

美國及九個地區的普通汽油與 2 號公路用柴油零售平均價。

提供多少歷史資料?

美國普通汽油自 1990 年 8 月 20 日開始,美國柴油自 1994 年 3 月 21 日開始。地區數列開始較晚,汽油自 1992 年起,柴油自 1997 年起;各數列會回報自己的 coverage_start。若要依日期區間查詢,請使用 observations 端點。

我要如何選擇地區?

以 commodity=gasoline 或 commodity=diesel 探索數列。閱讀 area 與 description,然後用該 series_id 取得詳細資料、最新價格或歷史資料。

使用資料之前應該檢查什麼?

燃料價格 API 涵蓋美國平均、東岸(PADD 1)、新英格蘭(PADD 1A)、大西洋中部(PADD 1B)、下大西洋(PADD 1C)、中西部(PADD 2)、墨西哥灣沿岸(PADD 3)、洛磯山脈(PADD 4)、西岸(PADD 5),以及不含加州的西岸。來源:U.S。Energy Information Administration