جميع واجهات API

واجهة API للسلع

أسعار المعادن الفورية والسلع الفعلية بوحداتها الأصلية وتعريفات سلاسلها.

احصل على مفتاح API مجاني
اقرأ التوثيق ‏←
متاح99.96% uptime, last 30 أيام357 ms زمن الاستجابة المعتاد

الطلب الأول

العثور على أسعار زيت النخيل في إندونيسيا

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/palmoil/physical?product=ffb&country=IDN" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
استجابة نموذجية
{
  "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",
      "unit_key": "kilogram",
      "coverage_start": "2026-08-19",
      "coverage_end": "2026-09-01",
      "frequency": "weekly"
    }
  ],
  "next_cursor": null
}

نقاط النهاية

واجهة API لأسعار المعادن الفورية

GETاحصل على سعر فوري/v1/commodities/spot/{commodity}/{currency}

احصل على سعر فوري أو سعر مرجعي مشتق من العقود الآجلة.

المعلمات

  • commodityمطلوب

    XAU وXAG وXPT وXPD وWTI (خام WTI) وBRENT (خام برنت) أو XCU (النحاس).

  • currencyمطلوب

    عملة التسعير بالأحرف الكبيرة. للذهب 31 عملة، وتُسعَّر البقية بالدولار الأمريكي فقط.

السعر

  • symbolسلسلة نصية

    السلعة وعملة التسعير، مثل XAU-USD.

  • currencyسلسلة نصية

    عملة التسعير.

  • unitسلسلة نصية

    troy_ounce للمعادن الثمينة، وbarrel لـ WTI وBRENT، وpound لـ XCU.

  • priceسلسلة نصية

    سعر إرشادي واحد موجب بصيغة سلسلة نصية لعدد عشري.

  • timestampتاريخ ووقت

    وقت السعر بتوقيت UTC.

  • staleمنطقي

    هل السعر قديم. السوق المغلق لا يجعل السعر قديمًا أبدًا.


المرجع الكامل ‏←
GETاحصل على أشرطة الأسعار/v1/commodities/spot/{commodity}/{currency}/bars

أشرطة الافتتاح والأعلى والأدنى والإغلاق للذهب والفضة والبلاتين والبلاديوم والنحاس وWTI وBRENT.

المعلمات

  • commodityمطلوب

    XAU وXAG وXPT وXPD وWTI (خام WTI) وBRENT (خام برنت) أو XCU (النحاس).

  • currencyمطلوب

    عملة التسعير بالأحرف الكبيرة. للذهب 31 عملة، وتُسعَّر البقية بالدولار الأمريكي فقط.

  • intervalاختياري

    1m أو 5m أو 15m أو 1h أو 4h أو 1d. القيمة الافتراضية 1d.

  • startمطلوب

    الشريط الأول، بتوقيت UTC عند حدّ فاصل زمني. شاملة.

  • endمطلوب

    الشريط الأخير، بتوقيت UTC عند حدّ فاصل زمني. غير شاملة.

  • limitاختياري

    عدد الأشرطة في الصفحة. القيمة الافتراضية 100 والحد الأقصى 500.

  • cursorاختياري

    أعد استخدام next_cursor من الصفحة السابقة مع الاستعلام نفسه.

حقول الاستجابة

  • barsمصفوفة

    أشرطة مغلقة من الأقدم إلى الأحدث، ولكل منها طابع زمني وسعر الافتتاح والأعلى والأدنى والإغلاق كنصوص عشرية. الذهب بعملات غير USD له سعر الإغلاق فقط.

  • next_cursorسلسلة نصية

    المؤشر للصفحة التالية. يكون Null عندما لا تبقى أشرطة.


المرجع الكامل ‏←

واجهة API لأسعار السلع الفعلية

GETاكتشف سلاسل الأسعار الفعلية في زيت النخيل/v1/commodities/palmoil/physical

ابحث عن سلاسل زيت النخيل المادية المعتمدة حسب المنتج والدولة.

المعلمات

  • productاختياري

    التصفية حسب المنتج الفعلي.

  • countryاختياري

    التصفية حسب البلد، مثل 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اختياري

    الحد الأقصى لعدد السلاسل في الصفحة. القيمة الافتراضية 100.

  • cursorاختياري

    تابع باستخدام next_cursor المعاد، مع إبقاء كل المرشحات الأصلية وlimit دون تغيير.

حقول الاستجابة

  • 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[].unit_keyسلسلة نصية

    unit_key هي الوحدة بصيغة كتابة قياسية واحدة، مثل troy_ounce أو barrel أو tonne؛ أما unit فتحتفظ بصياغة المصدر. عندما يُعرض السعر بالسنتات تكون price_scale تساوي 0.01: اضرب السعر فيها لتحصل على المبلغ بالعملة.

  • series[].producer_arrangementسلسلة نصية

    يظهر فقط في سلاسل جداول أسعار FFB الإندونيسية حسب عمر النخيل عندما يحدد المصدر ترتيبًا. ويُحذف في غير ذلك.

  • series[].frequency / series[].coverage_start / series[].coverage_endسلسلة نصية وتواريخ

    وتيرة النشر وحدود البيانات التاريخية المقبولة، دون ضمان خلو الفترة من الفجوات.

  • next_cursorسلسلة نصية أو null

    رمز لمتابعة الصفحات، أو null إذا لم توجد سلاسل أخرى.


المرجع الكامل ‏←
GETاحصل على أحدث سعر فعلي في زيت النخيل/v1/commodities/palmoil/physical/{series_id}

احصل على أحدث قراءة معتمدة لزيت النخيل.

المعلمات

  • series_idمطلوب

    استخدم معرّفًا تعيده واجهة الاكتشاف.

  • price_monthاختياري

    خاص بـMPOB CPO. يحدد شهرًا واحدًا للأسعار؛ ويستخدم افتراضيًا الشهر الذي ينتمي إليه كل تقرير.

حقول الاستجابة

  • series_idسلسلة نصية

    معرّف ثابت لسلسلة الأسعار الفعلية.

  • currency / unitسلاسل نصية

    العملة والوحدة الأصلية: kilogram لجداول FFB الإندونيسية، وmetric_ton لأسعار CPO، وone_percent_oer لمراجع FFB الماليزية.

  • unit_keyسلسلة نصية

    unit_key هي الوحدة بصيغة كتابة قياسية واحدة، مثل troy_ounce أو barrel أو tonne؛ أما unit فتحتفظ بصياغة المصدر. عندما يُعرض السعر بالسنتات تكون price_scale تساوي 0.01: اضرب السعر فيها لتحصل على المبلغ بالعملة.

  • period_start / period_endالتواريخ

    تشمل فترات سريان الأسعار يومي البداية والنهاية. أما MPOB فيستخدم فترة تبدأ بيوم التقرير وتنتهي في اليوم التالي، دون أن تشمل ذلك اليوم التالي.

  • revisionعدد صحيح

    رقم مراجعة السعر أو جدول الأسعار الكامل.

  • price or pricesسلسلة نصية عشرية أو مصفوفة كاملة

    سعر موجب بصيغة سلسلة نصية عشرية، أو مصفوفة prices كاملة تضم tree_age_min_years وtree_age_max_years وprice. يشمل نطاق العمر الحدين الأدنى والأقصى. وتبقى وحدة FFB الماليزي هي one_percent_oer.

  • price_monthYYYY-MM

    مطلوب لأسعار MPOB CPO ويحدد شهر السعر. ويحدد period_start وperiod_end فترة القراءة الخاصة بيوم التقرير.


المرجع الكامل ‏←
GETاحصل على سجل الأسعار الفعلية في زيت النخيل/v1/commodities/palmoil/physical/{series_id}/observations

احصل على قراءات زيت النخيل بدءًا من الأقدم.

المعلمات

  • series_idمطلوب

    السلسلة التي تعيدها واجهة الاكتشاف.

  • startاختياري

    بداية نطاق البحث، مع شمول هذا اليوم. يجب تقديمها مع end. تُدرج فترات السريان الإندونيسية إذا تداخلت مع النطاق، وتُختار الأسعار اليومية الماليزية حسب تاريخ التقرير.

  • endاختياري

    حد أعلى غير مشمول. يجب أن يكون لاحقًا لـstart.

  • limitاختياري

    الحد الأقصى لعدد القراءات المعادة. القيمة الافتراضية 100، وتبقى جداول الأعمار كاملة.

  • cursorاختياري

    تابع دون تغيير أي من المعلمات الأصلية، بما فيها series_id والتواريخ وlimit وprice_month. قد يؤدي تغيير البيانات المنشورة إلى انتهاء صلاحية المؤشر.

  • price_monthاختياري

    خاص بـMPOB CPO. يحدد شهرًا واحدًا للأسعار؛ ويستخدم افتراضيًا الشهر الذي ينتمي إليه كل تقرير.

حقول الاستجابة

  • series_idسلسلة نصية

    معرّف ثابت لسلسلة الأسعار الفعلية.

  • currency / unitسلاسل نصية

    العملة والوحدة الأصلية المشتركتان بين جميع القراءات.

  • unit_keyسلسلة نصية

    unit_key هي الوحدة بصيغة كتابة قياسية واحدة، مثل troy_ounce أو barrel أو tonne؛ أما unit فتحتفظ بصياغة المصدر. عندما يُعرض السعر بالسنتات تكون price_scale تساوي 0.01: اضرب السعر فيها لتحصل على المبلغ بالعملة.

  • observationsمصفوفة

    الفترة ورقم المراجعة والقيمة السعرية المفردة أو جدول الأسعار الكامل، مرتبة من الأقدم إلى الأحدث. تحتفظ صفوف MPOB CPO بالحقل price_month، وصفوف CPO وFFB الماليزية بالفترة period_start/period_end الخاصة بيوم التقرير.

  • next_cursorسلسلة نصية أو null

    رمز متابعة غير قابل للتفسير، أو null في النهاية.


المرجع الكامل ‏←

حالات الاستخدام

سعر النفط للتر والغالون

حوّل برنت أو WTI من دولارات للبرميل إلى لترات وغالونات.

اقرأ الدليل ‏←

سعر النحاس للكيلوغرام والطن

حوّل النحاس من دولارات للرطل إلى كيلوغرامات وأطنان متريّة.

اقرأ الدليل ‏←

نسبة الذهب إلى الفضة

اقسم الذهب على الفضة لتواريخ أو أوقات متطابقة.

اقرأ الدليل ‏←

تنبيهات الأسعار

أرسل تنبيهًا عندما يتجاوز الذهب الحد الذي تحدده.

اقرأ الدليل ‏←

التغطية

اعرض جميع السلع البالغ عددها 53

واجهات API ذات صلة

واجهة API لأسعار المعادن الفورية

أسعار الذهب والفضة والبلاتين والبلاديوم الفورية، إضافة إلى أسعار WTI وبرنت والنحاس المرجعية.

استكشف API ‏←

واجهة API لأسعار السلع الفعلية

زيت النخيل وأسعار النفط والغاز اليومية وأسعار الوقود الأسبوعية للتجزئة في أمريكا والمؤشرات السلعية الشهرية، بالوحدات كما نُشرت.

استكشف API ‏←

واجهة برمجة أسعار الصرف

أسعار الصرف الحالية وتحويل العملات وسجل الأسعار المخزَّن.

استكشف API ‏←

الأسعار

البدء مجاني. رصيد مجاني بقيمة 10 دولارات كل شهر، ثم 2 دولار لكل 1,000 استدعاء.

عرض الأسعار ‏←

الأسئلة الشائعة

أي واجهة سلع متاحة؟

يغطي الإصدار المتاح حاليًا المعادن الفورية والسلع الفعلية. العقود الآجلة غير متاحة للعامة.

هل يمكنني استرجاع الأسعار التاريخية؟

نعم. اطلب قراءات لسلسلة زيت نخيل مقبولة؛ وتحافظ الاستجابة على الوحدات الأصلية وتواريخ السريان والمراجعات والفجوات في بيانات المصدر.

ما الذي يجب أن أتحقق منه قبل استخدام البيانات؟

تبقى الوحدات وأنواع الأسعار والجغرافيا والفترات السارية مرتبطة بكل سلسلة معتمدة. منتجات العقود الآجلة غير متاحة للعموم حاليًا.