واجهة سلاسل السلع المادية API

ابحث عن سلاسل Palmoil 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`	سلاسل نصية أو قيمة فارغة	نعم	نطاق السوق والمنتج الدقيق.
`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.