棕榈油实物历史数据 API

按时间从旧到新获取棕榈油观测值

端点与请求

REST 端点

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

接口契约请求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical/id-ri-oil-palm-ffb-smallholder-purchase-agreement/observations?start=2026-08-01&end=2026-09-02&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

参数

名称	必填	类型	含义
`series_id`	是	路径参数 · 稳定的 Narwhal 标识符	由发现接口返回的序列。
`start`	否	查询·YYYY-MM-DD	查询范围的起始日包含在内，必须同时提供 end。印度尼西亚价格的有效期只要与查询范围重叠就会纳入结果；马来西亚每日价格则按报告日期筛选。
`end`	否	查询·YYYY-MM-DD	不包含的上限，必须晚于 start。
`limit`	否	查询·整数，1–500	返回的最大观测值数量。默认为 100；树龄价目表始终保持完整。
`cursor`	否	查询·不透明字符串	继续请求时，保持所有原始参数不变，包括 series_id、日期、limit 和 price_month。已发布数据发生变化可能导致游标过期。
`price_month`	否	查询·YYYY-MM	仅适用于 MPOB CPO。选择一个报价月份；默认使用每份报告自身所属的月份。

响应

接口契约示例

{
  "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
  "currency": "IDR",
  "unit": "kilogram",
  "observations": [
    {
      "period_start": "2026-08-26",
      "period_end": "2026-09-01",
      "revision": 1,
      "prices": [
        {
          "tree_age_min_years": 3,
          "tree_age_max_years": 3,
          "price": "2998.31"
        },
        {
          "tree_age_min_years": 4,
          "tree_age_max_years": 4,
          "price": "3347.20"
        },
        {
          "tree_age_min_years": 5,
          "tree_age_max_years": 5,
          "price": "3595.38"
        },
        {
          "tree_age_min_years": 6,
          "tree_age_max_years": 6,
          "price": "3734.94"
        },
        {
          "tree_age_min_years": 7,
          "tree_age_max_years": 7,
          "price": "3818.86"
        },
        {
          "tree_age_min_years": 8,
          "tree_age_max_years": 8,
          "price": "3865.46"
        },
        {
          "tree_age_min_years": 9,
          "tree_age_max_years": 9,
          "price": "3878.72"
        },
        {
          "tree_age_min_years": 10,
          "tree_age_max_years": 20,
          "price": "3836.93"
        },
        {
          "tree_age_min_years": 21,
          "tree_age_max_years": 21,
          "price": "3770.94"
        },
        {
          "tree_age_min_years": 22,
          "tree_age_max_years": 22,
          "price": "3695.31"
        },
        {
          "tree_age_min_years": 23,
          "tree_age_max_years": 23,
          "price": "3609.33"
        },
        {
          "tree_age_min_years": 24,
          "tree_age_max_years": 24,
          "price": "3544.29"
        },
        {
          "tree_age_min_years": 25,
          "tree_age_max_years": 25,
          "price": "3490.84"
        },
        {
          "tree_age_min_years": 26,
          "tree_age_max_years": 26,
          "price": "3471.62"
        },
        {
          "tree_age_min_years": 27,
          "tree_age_max_years": 27,
          "price": "3441.82"
        },
        {
          "tree_age_min_years": 28,
          "tree_age_max_years": 28,
          "price": "3385.41"
        },
        {
          "tree_age_min_years": 29,
          "tree_age_max_years": 29,
          "price": "3344.02"
        },
        {
          "tree_age_min_years": 30,
          "tree_age_max_years": 30,
          "price": "3249.41"
        }
      ]
    }
  ],
  "next_cursor": null
}

字段	类型	必填	含义
`series_id`	字符串	是	实物数据序列的稳定标识符。
`currency / unit`	字符串	是	所有观测值共用的币种和原始单位。
`observations`	数组	是	期间、修订版本及单一价格或完整价目表，按时间从早到晚排列。MPOB CPO 行保留 price_month；马来西亚 CPO 和 FFB 行保留报告日对应的 period_start/period_end。
`next_cursor`	字符串或 null	是	不透明的延续令牌，结束时为 null。

错误与配额

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

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

覆盖范围

已接纳的历史数据因序列而异。马来西亚档案中已注明报告缺口；印度尼西亚 FFB 的覆盖范围因地区而异。

使用 Narwhal API 密钥即可访问。