棕榈油实物数据序列 API

按产品和国家查找已接纳的棕榈油实物数据序列

端点与请求

REST 端点

GET /v1/commodities/palmoil/physical

接口契约请求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical?product=ffb&country=IDN&area=ID-RI&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

参数

名称	必填	类型	含义
`product`	否	查询参数 · ffb 或 cpo	按实物产品筛选。
`country`	否	查询·ISO 3166-1 alpha-3	按国家筛选，例如 IDN。
`area`	否	查询参数 · 地区标识符	使用发现接口返回的地区标识符：适用时使用 ISO 3166-2，否则使用 Narwhal 定义的 nwl-* 标识符，例如 nwl-mys-north。
`price_type`	否	查询参数 · 枚举值	official_purchase_schedule、government_reference 或 market_average。该值必须与产品相容。
`currency`	否	查询参数 · 币种代码	按原始币种筛选，例如 IDR、USD 或 MYR。此操作不会换算价格。
`producer_type`	否	查询·smallholder	适用于印度尼西亚 FFB 收购价目表；不能与 product=cpo 一起使用。
`producer_arrangement`	否	查询参数 · 枚举值	purchase_agreement 或 supported_scheme。适用于印度尼西亚 FFB 价目表；不能与 product=cpo 一起使用。
`limit`	否	查询·整数，1–500	每页的最大序列数量。默认为 100。
`cursor`	否	查询·不透明字符串	使用返回的 next_cursor 继续请求，并保持所有原始筛选条件和 limit 不变。

响应

接口契约示例

{
  "series": [
    {
      "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
      "commodity": "palmoil",
      "product": "ffb",
      "observation_type": "age_schedule",
      "period_type": "effective",
      "country": "IDN",
      "area": "ID-RI",
      "producer_type": "smallholder",
      "producer_arrangement": "purchase_agreement",
      "price_type": "official_purchase_schedule",
      "currency": "IDR",
      "unit": "kilogram",
      "coverage_start": "2026-08-19",
      "coverage_end": "2026-09-01",
      "frequency": "weekly"
    }
  ],
  "next_cursor": null
}

字段	类型	必填	含义
`series`	数组	是	按稳定的 series_id 排序的完整已批准数据序列。
`series[].series_id`	字符串	是	历史数据操作使用的稳定标识符。
`series[].commodity / series[].product / series[].country / series[].area`	字符串；area 可以为 null	是	产品及地理范围。全国序列的 area=null；地区标识符可能使用 nwl-* 命名空间。
`series[].observation_type / series[].period_type`	枚举值	是	scalar 或 age_schedule；effective 或 observation。这些字段定义响应类型及日期含义。
`series[].price_type / series[].currency / series[].unit`	字符串	是	来源定义的价格类型、币种和原始单位。
`series[].producer_type / series[].producer_arrangement`	字符串；arrangement 可以为 null	否	仅出现在印度尼西亚 FFB 树龄价目表序列中；单一数值序列不包含这些字段。
`series[].frequency / series[].coverage_start / series[].coverage_end`	字符串和日期	是	发布频率及已接纳的历史日期范围，不保证覆盖期间内没有缺口。
`next_cursor`	字符串或 null	是	用于继续分页的令牌；若无更多序列，则为 null。

错误与配额

400 invalid_query — 代码、区域、日期范围、限制或选择器无效。
401 invalid_api_key — Bearer 密钥缺失或被拒绝。
429 rate_limit_exceeded 或 quota_exhausted — 共用配额已耗尽。
503 physical_price_unavailable — 完整发布版本无法安全满足该接口。

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

覆盖范围

发现接口列出已接纳的印度尼西亚和马来西亚 CPO/FFB 序列。筛选条件保留产品、地区、价格类型和原始单位的区别。

使用 Narwhal API 密钥即可访问。