واجهة 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 ثابت	استخدم معرّفًا تعيده واجهة الاكتشاف.
`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`	سلاسل نصية	نعم	العملة والوحدة الأصلية: kilogram لجداول FFB الإندونيسية، وmetric_ton لأسعار CPO، وone_percent_oer لمراجع FFB الماليزية.
`period_start / period_end`	التواريخ	نعم	تشمل فترات سريان الأسعار يومي البداية والنهاية. أما MPOB فيستخدم فترة تبدأ بيوم التقرير وتنتهي في اليوم التالي، دون أن تشمل ذلك اليوم التالي.
`revision`	عدد صحيح	نعم	رقم مراجعة السعر أو جدول الأسعار الكامل.
`price or prices`	سلسلة نصية عشرية أو مصفوفة كاملة	نعم	سعر موجب بصيغة سلسلة نصية عشرية، أو مصفوفة prices كاملة تضم tree_age_min_years وtree_age_max_years وprice. يشمل نطاق العمر الحدين الأدنى والأقصى. وتبقى وحدة FFB الماليزي هي one_percent_oer.
`price_month`	YYYY-MM	لا	مطلوب لأسعار MPOB CPO ويحدد شهر السعر. ويحدد period_start وperiod_end فترة القراءة الخاصة بيوم التقرير.

الأخطاء والحصة

400 invalid_query — الرمز أو المنطقة أو نطاق التاريخ أو الحد أو المحدد غير صالح.
401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
403 plan_upgrade_required — الفترة أو البداية المطلوبة تسبق نافذة السجل في خطتك (Free لمدة 12 شهرًا، وBasic لمدة 5 سنوات، وPro للسجل الكامل).
404 palmoil_series_not_found — لا توجد بيانات معتمدة كاملة تطابق الطلب.
429 rate_limit_exceeded أو quota_exhausted — استُنفدت الحصة المشتركة.
503 palmoil_unavailable — لا يمكن تلبية متطلبات الواجهة بأمان باستخدام إصدار كامل.

لا تستهلك الطلبات المرفوضة وأخطاء الخادم الحصة الشهرية.

التغطية

يعيد CPO وFFB الماليزي قيمًا سعرية مفردة. ويحافظ FFB الإندونيسي على جداول الأعمار كاملة. إذا أفاد أحدث تقرير بعدم وجود تداول، فلن يُعرض سعر أقدم على أنه السعر الحالي.

متاح باستخدام مفتاح Narwhal API.