棕櫚油實體商品歷史資料 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 ID	探索介面回傳的序列。
`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 金鑰即可存取。