棕櫚油實體商品價格 API

取得已接受的最新棕櫚油觀測值

端點與請求

REST 端點

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

介面契約請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical/id-ri-oil-palm-ffb-smallholder-purchase-agreement" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_get_palmoil_physical_price。REST 和 MCP 共用相同的結構描述、帳戶配額、授權檢查與問題格式。

參數

名稱	必填	類型	含義
`series_id`	是	路徑參數 · 穩定的 Narwhal ID	使用探索介面回傳的 ID。
`price_month`	否	查詢·YYYY-MM	僅適用於 MPOB CPO。選擇一個報價月份；預設為各報告自身所屬的月份。

回應

介面契約範例

{
  "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
  "currency": "IDR",
  "unit": "kilogram",
  "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"
    }
  ]
}

欄位	類型	必填	含義
`series_id`	字串	是	穩定的實體商品序列識別碼。
`currency / unit`	字串	是	貨幣與原始單位：印尼 FFB 價目表使用 kilogram，CPO 使用 metric_ton，馬來西亞 FFB 參考價使用 one_percent_oer。
`period_start / period_end`	日期	是	有效價格的日期範圍包含起訖日。MPOB 則以報告日為起日、次日為迄日，且不含迄日。
`revision`	整數	是	價格或完整價目表的修訂版本。
`price or prices`	十進位字串或完整陣列	是	以十進位字串表示的正數價格，或包含 tree_age_min_years、tree_age_max_years 和 price 的完整 prices 陣列。樹齡上下限均包含在內。馬來西亞 FFB 仍使用 one_percent_oer。
`price_month`	YYYY-MM	否	MPOB CPO 報價必填，用來識別報價月份；period_start 和 period_end 則標示報告日的觀測區間。

錯誤與配額

400 invalid_query — 代碼、區域、日期範圍、限制或選擇器無效。
401 invalid_api_key — Bearer 金鑰缺失或被拒絕。
404 palmoil_series_not_found — 沒有完整且已核准的資料符合請求。
409 physical_series_ambiguous — 選擇器匹配了多個序列。
429 rate_limit_exceeded 或 quota_exhausted — 共享配額已耗盡。
503 physical_price_unavailable — 完整發布版本無法安全滿足該介面。

遭拒的請求和伺服器錯誤不會消耗每月配額。

涵蓋範圍

CPO 和馬來西亞 FFB 回傳單一價格數值。印尼 FFB 保留完整的樹齡價目表。最新報告若顯示無交易，絕不會以舊價格冒充目前價格。

使用 Narwhal API 金鑰即可存取。