实物价格序列 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 密钥即可访问。