以你的貨幣顯示價格
用匯率把商品價格換算成你自己的貨幣。
閱讀指南 →油價 API 提供 1990 年起的汽油歷史價格與 1994 年起的柴油價格,每週更新,單位為美元每美制加侖。資料來源:美國能源資訊署(EIA)。
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
}/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 說明價格定義,來源未提供時省略。
/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基準價格為每月資料。
/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開始,後續發布修改該期間的數值時遞增。
/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 表示最後一頁。
美國及九個地區的普通汽油與 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
12 個月內每月贈送 10 美元免費額度,無需綁卡。每月 10 美元免費額度,無需綁卡。