實物商品序列 API

按地區查找棕櫚油 FFB 序列

端点與請求

REST 端點

GET /v1/commodities/physical/{commodity}/{country}

契約請求

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/OIL-PALM-FFB/IDN?area=ID-RI&currency=IDR" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用 commodities_discover_physical_series。REST 和 MCP 使用相同的結構、帳戶額度、權限檢查和問題格式。

參數

名稱	必填	類型	含義
`commodity`	是	路徑·目錄代碼	穩定的商品代碼。Palmoil 分片使用 OIL-PALM-FFB。
`country`	是	路徑·ISO 3166-1 alpha-3	擁有現貨市場的國家。首個研究國家是 IDN。
`area`	否	查詢·ISO 3166-2 或 Narwhal 區域	行政區域或來源定義的市場區域，例如代表廖內的 ID-RI。
`currency`	否	查詢·ISO 4217	按發布時使用的貨幣篩選序列。

回應

契約示例

{
  "commodity": "OIL-PALM-FFB",
  "country": "IDN",
  "series": [
    {
      "series_id": "id-ri-oil-palm-ffb-smallholder-purchase-agreement",
      "commodity": "OIL-PALM-FFB",
      "country": "IDN",
      "area": "ID-RI",
      "producer_type": "smallholder",
      "producer_arrangement": "purchase_agreement",
      "price_basis": "official_purchase_schedule",
      "currency": "IDR",
      "unit": "kilogram",
      "coverage_start": "2026-08-19",
      "coverage_end": "2026-09-01",
      "latest_released_on": "2026-08-26",
      "schedule_count": 2
    }
  ]
}

欄位	類型	必填	含義
`commodity / country`	字串	是	所請求的實物市場範圍。
`series`	陣列	是	按穩定 series_id 排序的完整已批准序列。
`series_id`	字串	是	歷史操作使用的穩定身份。
`area / producer_type / producer_arrangement`	字串或 null	是	確切的市場和生產者範圍。
`coverage_start / coverage_end`	日期	是	已批准序列中的首個和最後一個生效日期。
`latest_released_on / schedule_count`	日期和整數	是	最新官方發布日期和已批准日程數量。

錯誤與配額

400 invalid_query — 代碼、區域、日期範圍、限制或選擇器無效。
401 invalid_api_key — Bearer 密鑰缺失或被拒絕。
404 physical_series_not_found — 沒有完整的已批准數據符合請求。
429 rate_limit_exceeded 或 quota_exhausted — 共享額度已耗盡。
503 physical_price_unavailable — 完整發布版本無法安全滿足該介面。

被拒絕的請求和服務器錯誤不會消耗月度配額。

覆蓋範圍

僅顯示完整且獲批准的序列。首個選定國家是印度尼西亞。

使用 Narwhal API 密鑰即可獲得。