棕櫚油實體商品序列 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`	否	查詢參數 · 地區 ID	使用探索介面回傳的地區：適用時為 ISO 3166-2，或 Narwhal 定義的 nwl-* ID，例如 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 金鑰即可存取。