实物价格序列详情 API

读取一个燃油周度序列或月度基准序列的定义、单位和覆盖范围。

端点与请求

REST 端点

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

接口契约请求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-regular-gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_get_physical_series。REST 和 MCP 使用相同的数据结构、账户配额、使用权检查和错误响应格式。

参数

名称	必填	类型	含义
`series_id`	是	路径 · 字符串	请使用发现操作返回的稳定 ID，例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。

来源: 美国能源信息署。来源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

响应

接口契约示例

{
  "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"
}

字段	类型	必填	含义
`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
`commodity / category / product`	字符串	是	商品、类别和产品定义。例如 gasoline / energy / regular-gasoline 和 copper / metals / copper。发现操作会返回各序列的对应值。
`market / area`	字符串 / 字符串或 null	是	计价市场和可选的区域范围。WLD 表示全球基准，EUU 表示欧盟，国家市场使用 ISO alpha-3 代码。美国燃油使用 USA，全美平均值的 area 为 null。
`price_type / basis`	字符串 / 字符串或 null	是	燃油使用 retail_average。月度序列使用 international_benchmark，但烟草使用 import_unit_value。basis 在信息可用时说明价格定义。
`frequency`	字符串	是	美国燃油为 weekly，世界银行基准为 monthly。
`description / publisher`	字符串	是	序列定义和发布机构。
`coverage_start / coverage_end`	日期	是	最早观测值的首日和最新观测值的末日，包含这两个日期。部分序列起始较晚或已结束。日期边界不保证历史数据连续无缺口。

错误与配额

400 invalid_query, 代码、区域、日期范围、limit 或选择器无效。
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 密钥即可访问。