最新实物价格 API

读取最新可用的燃油周度价格或月度基准价格及其观测期间。

端点与请求

REST 端点

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

接口契约请求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/latest" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_get_physical_latest。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

响应

接口契约示例

{
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "price": "14474",
  "published_on": null,
  "revision": 1,
  "series_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)"
}

字段	类型	必填	含义
`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
`period_start / period_end`	日期	是	观测日期，包含起止日期。燃油的两个日期均为周一调查日期。月度观测值覆盖整个月，例如2026-09-01至2026-09-30。
`price`	十进制字符串	是	以序列货币发布的价格，每 unit_quantity 个单位计价。请结合序列的价格类型和 basis 解读。
`published_on`	日期或 null	是	发布日期（如有）。日期未知时保留 null。
`revision`	整数	是	从1开始，后续发布修改该期间的数值时递增。

错误与配额

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 密钥即可访问。