واجهة 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 ثابت	السلسلة التي تعيدها واجهة الاكتشاف.
`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 مفقود أو مرفوض.
403 plan_upgrade_required — الفترة أو البداية المطلوبة تسبق نافذة السجل في خطتك (Free لمدة 12 شهرًا، وBasic لمدة 5 سنوات، وPro للسجل الكامل).
404 palmoil_series_not_found — لا توجد بيانات معتمدة كاملة تطابق الطلب.
409 cursor_expired, تغير إصدار البيانات. أعد بدء التصفح بالصفحات دون مؤشر.
429 rate_limit_exceeded أو quota_exhausted — استُنفدت الحصة المشتركة.
503 palmoil_unavailable — لا يمكن تلبية متطلبات الواجهة بأمان باستخدام إصدار كامل.

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

التغطية

تختلف البيانات التاريخية المقبولة باختلاف السلسلة. توجد فجوات موثقة في تقارير الأرشيف الماليزي، بينما تختلف تغطية FFB الإندونيسي باختلاف المنطقة.

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