واجهة 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`	لا	الاستعلام · معرّف المنطقة	استخدم معرّف منطقة تعيده واجهة الاكتشاف: ISO 3166-2 حيث ينطبق، أو معرّف nwl-* يحدده Narwhal مثل nwl-mys-north.
`price_type`	لا	استعلام · تعداد	official_purchase_schedule أو government_reference أو market_average. يجب أن تتوافق القيمة مع المنتج.
`currency`	لا	الاستعلام · رمز العملة	التصفية حسب العملة الأصلية، مثل IDR أو USD أو MYR. لا يؤدي ذلك إلى تحويل الأسعار.
`producer_type`	لا	الاستعلام · صاحب الحيازة الصغيرة	ينطبق على جداول شراء 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",
      "product": "ffb",
      "observation_type": "age_schedule",
      "period_type": "effective",
      "country": "IDN",
      "area": "ID-RI",
      "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[].product / series[].country`	سلاسل نصية	نعم	نطاق المنتج والنطاق الجغرافي.
`series[].area`	سلسلة نصية	لا	تُحذف area في السلاسل الوطنية. قد تستخدم المعرّفات الإقليمية نطاق الأسماء nwl-*.
`series[].observation_type / series[].period_type`	التعدادات	نعم	scalar أو age_schedule؛ وeffective أو observation. تحدد هذه القيم شكل الاستجابة ومعنى التواريخ.
`series[].price_type / series[].currency / series[].unit`	سلاسل نصية	نعم	نوع السعر الذي يحدده المصدر، والعملة، والوحدة الأصلية.
`series[].producer_arrangement`	سلسلة نصية	لا	يظهر فقط في سلاسل جداول أسعار FFB الإندونيسية حسب عمر النخيل عندما يحدد المصدر ترتيبًا. ويُحذف في غير ذلك.
`series[].frequency / series[].coverage_start / series[].coverage_end`	سلسلة نصية وتواريخ	نعم	وتيرة النشر وحدود البيانات التاريخية المقبولة، دون ضمان خلو الفترة من الفجوات.
`next_cursor`	سلسلة نصية أو null	نعم	رمز لمتابعة الصفحات، أو null إذا لم توجد سلاسل أخرى.

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

400 invalid_query — الرمز أو المنطقة أو نطاق التاريخ أو الحد أو المحدد غير صالح.
400 invalid_cursor — المؤشر غير صالح أو لا يطابق السلسلة والنطاق.
401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
409 cursor_expired, تغير إصدار البيانات. أعد بدء التصفح بالصفحات دون مؤشر.
429 rate_limit_exceeded أو quota_exhausted — استُنفدت الحصة المشتركة.
503 palmoil_unavailable — لا يمكن تلبية متطلبات الواجهة بأمان باستخدام إصدار كامل.

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

التغطية

تسرد واجهة الاكتشاف سلاسل CPO وFFB المقبولة من إندونيسيا وماليزيا. وتحافظ المرشحات على الفروق بين المنتج والمنطقة ونوع السعر والوحدة الأصلية.

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