实物商品序列 API

按地区查找棕榈油 FFB 序列

端点与请求

REST 端点

GET /v1/commodities/physical/{commodity}/{country}

契约请求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/OIL-PALM-FFB/IDN?area=ID-RI&currency=IDR" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_discover_physical_series。REST 和 MCP 使用相同的结构、账户额度、权限检查和问题格式。

参数

名称	必填	类型	含义
`commodity`	是	路径·目录代码	稳定的商品代码。Palmoil 分片使用 OIL-PALM-FFB。
`country`	是	路径·ISO 3166-1 alpha-3	拥有现货市场的国家。首个研究国家是 IDN。
`area`	否	查询·ISO 3166-2 或 Narwhal 区域	行政区域或来源定义的市场区域，例如代表廖内的 ID-RI。
`currency`	否	查询·ISO 4217	按发布时使用的货币筛选序列。

响应

契约示例

{
  "commodity": "OIL-PALM-FFB",
  "country": "IDN",
  "series": [
    {
      "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
      "commodity": "OIL-PALM-FFB",
      "country": "IDN",
      "area": "ID-RI",
      "producer_type": "smallholder",
      "producer_arrangement": "purchase_agreement",
      "price_basis": "official_purchase_schedule",
      "currency": "IDR",
      "unit": "kilogram",
      "coverage_start": "2026-08-19",
      "coverage_end": "2026-09-01",
      "latest_released_on": "2026-08-26",
      "schedule_count": 2
    }
  ]
}

字段	类型	必填	含义
`commodity / country`	字符串	是	所请求的实物市场范围。
`series`	数组	是	按稳定 series_id 排序的完整已批准序列。
`series_id`	字符串	是	历史操作使用的稳定身份。
`area / producer_type / producer_arrangement`	字符串或 null	是	确切的市场和生产者范围。
`coverage_start / coverage_end`	日期	是	已批准序列中的首个和最后一个生效日期。
`latest_released_on / schedule_count`	日期和整数	是	最新官方发布日期和已批准日程数量。

错误与配额

400 invalid_query — 代码、区域、日期范围、限制或选择器无效。
401 invalid_api_key — Bearer 密钥缺失或被拒绝。
404 physical_series_not_found — 没有完整的已批准数据符合请求。
429 rate_limit_exceeded 或 quota_exhausted — 共享额度已耗尽。
503 physical_price_unavailable — 完整发布版本无法安全满足该接口。

被拒绝的请求和服务器错误不会消耗月度配额。

覆盖范围

仅显示完整且获批准的序列。首个选定国家是印度尼西亚。

使用 Narwhal API 密钥即可获得。