实物价格历史 API

读取燃油周度价格或商品月度价格历史，包括期间、发布时的单位和修订信息。

端点与请求

REST 端点

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

接口契约请求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/observations?start=2026-07-01&end=2026-10-01&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

参数

名称	必填	类型	含义
`series_id`	是	路径 · 字符串	请使用发现操作返回的稳定 ID，例如 fuel-eia-usa-regular-gasoline 或 worldbank-cmo-copper。
`start`	否	查询·YYYY-MM-DD	包含起始日期。请同时提供 start 和 end，或同时省略两者。
`end`	否	查询·YYYY-MM-DD	结束日期不包含在内，且必须晚于 start。返回与该日期窗口重叠的观测值。
`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_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)",
  "observations": [
    {
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "price": "13543",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "price": "14326",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "price": "14474",
      "published_on": null,
      "revision": 1
    }
  ],
  "next_cursor": 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 金额计。数值不作换算。
`attribution`	字符串或 null	是	请随数据保留响应中的来源署名。来源: 美国能源信息署。来源: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`observations`	数组	是	观测值按从旧到新排序。每项包含 period_start、period_end、以十进制字符串表示的 price、可为 null 的 published_on 和 revision。
`observations[].period_start / observations[].period_end`	日期	是	观测日期，包含起止日期。燃油的两个日期均为周一调查日期。月度观测值覆盖整个月，例如2026-09-01至2026-09-30。
`observations[].price`	十进制字符串	是	以序列货币发布的价格，每 unit_quantity 个单位计价。请结合序列的价格类型和 basis 解读。
`observations[].published_on`	日期或 null	是	发布日期（如有）。日期未知时保留 null。
`observations[].revision`	整数	是	从1开始，后续发布修改该期间的数值时递增。
`next_cursor`	字符串或 null	是	无需解析内部结构的续页令牌。null 表示最后一页。

错误与配额

400 invalid_query, 代码、区域、日期范围、limit 或选择器无效。
400 invalid_cursor, 游标无效或与请求筛选条件不匹配。
400 cursor_expired, 发布数据已更改。请不带游标重新开始分页查询。
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 密钥即可访问。