所有 API

美国燃料价格 API

美国油价 API 提供自 1990 年起的汽油价格和自 1994 年起的柴油价格,按周更新,单位为美元每美制加仑。来源:美国能源信息署。

在线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