جميع واجهات API

واجهة أسعار الوقود الأمريكية API

API أسعار البنزين التاريخية منذ 1990 وأسعار الديزل منذ 1994، أسبوعياً بالدولار الأمريكي للغالون الأمريكي. المصدر: U.S. Energy Information Administration

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

الطلب الأول

ابحث عن سلاسل البنزين الأمريكية

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series?commodity=gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
استجابة نموذجية
{
  "series": [
    {
      "series_id": "fuel-eia-usa-regular-gasoline",
      "commodity": "gasoline",
      "category": "energy",
      "product": "regular-gasoline",
      "country": "USA",
      "price_type": "retail_average",
      "basis": "cash self-serve pump price incl. all taxes, 8:00 a.m. Monday",
      "currency": "USD",
      "unit": "us_gallon",
      "unit_key": "gallon",
      "unit_quantity": "1",
      "frequency": "weekly",
      "description": "United States: regular gasoline (all formulations), weekly average retail price in dollars per gallon from EIA's Monday survey (series EMM_EPMR_PTE_NUS_DPG.W).",
      "attribution": "Source: U.S. Energy Information Administration",
      "coverage_start": "1990-08-20",
      "coverage_end": "2026-10-19"
    }
  ],
  "next_cursor": null
}

نقاط النهاية

GETاكتشاف سلاسل الأسعار الفعلية/v1/commodities/physical/series

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

المعلمات

  • commodityاختياري

    صفِّ حسب السلعة، مثل gasoline أو diesel أو copper أو urea أو rice أو crude-oil أو coffee. استخدم قيمة commodity التي يعيدها الاكتشاف.

  • categoryاختياري

    الفئات المشمولة هي softs وoils-oilseeds وmetals وgrains وenergy وfertilizers وforestry وlivestock-dairy. تستخدم سلاسل الوقود energy.

  • countryاختياري

    استخدم WLD للأسعار المرجعية العالمية أو EUU للاتحاد الأوروبي. رموز البلدان المشمولة هي USA وTHA وJPN وAUS وZAF وMYS وCMR وVNM وMEX وLKA وIND وKEN. يستخدم الوقود الأمريكي USA.

  • price_typeاختياري

    يستخدم الوقود retail_average. تستخدم سلاسل EIA الفورية اليومية وسلاسل World Bank القيمة international_benchmark، باستثناء التبغ الذي يستخدم import_unit_value.

  • currencyاختياري

    صفِّ حسب عملة التسعير. يستخدم كلا المصدرين USD حاليًا.

  • limitاختياري

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

  • cursorاختياري

    استخدم next_cursor من الصفحة السابقة مع عوامل التصفية نفسها وlimit نفسه. تعني null عدم وجود صفحات أخرى.

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

  • seriesمصفوفة

    سلاسل تتضمن commodity وproduct وcountry وarea وأساس السعر basis وcurrency وunit وfrequency وattribution وتواريخ التغطية. تعني المصفوفة الفارغة عدم وجود سلسلة مطابقة.

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

    معرّف ثابت يعيده اكتشاف السلاسل.

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

    عملة التسعير. تستخدم سلاسل الوقود الأمريكي والأسعار المرجعية الشهرية USD.

  • series[].unit / series[].unit_quantityسلاسل نصية

    الوحدة المنشورة والكمية التي يُحسب السعر على أساسها. يستخدم الوقود us_gallon. تستخدم الأسعار المرجعية الشهرية metric_ton أو kilogram أو barrel أو cubic_meter أو troy_ounce أو mmbtu أو dry_metric_ton_unit أو sheet. الكمية هي 1، باستثناء الخشب الرقائقي الذي يستخدم USD لكل 100 لوح. لا تُحوّل القيم.

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

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

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

    احتفظ بنسب البيانات إلى مصدرها الوارد في الاستجابة مع البيانات. المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

  • series[].commodity / series[].category / series[].productسلاسل نصية

    تعريف السلعة والفئة والمنتج. تشمل الأمثلة gasoline / energy / regular-gasoline وcopper / metals / copper. يعيد الاكتشاف القيم الخاصة بكل سلسلة.

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

    يسمّي commodity_key السلعة بالطريقة نفسها في الأسعار الفورية والآجلة وأسعار التوقعات والأسعار الفعلية، مثل gold أو crude-oil. ويحمل النفط الخام أيضاً benchmark (القيمة wti أو brent أو urals أو dubai)، وتحمل العقود الآجلة exchange_mic، وهو الرمز القياسي للبورصة.

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

    يحدد area النطاق الإقليمي ويُحذف في السلاسل الوطنية.

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

    يعني WLD معيارًا عالميًا. يعني EUU الاتحاد الأوروبي. تستخدم البلدان رموز ISO alpha-3. يستخدم الوقود الأمريكي الرمز USA للمتوسط الوطني.

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

    يستخدم الوقود retail_average. تستخدم سلاسل EIA الفورية اليومية والسلاسل الشهرية international_benchmark، باستثناء التبغ الذي يستخدم import_unit_value.

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

    يصف basis تعريف السعر ويُحذف عندما لا يقدمه المصدر.

المرجع الكامل ‏←
GETالحصول على تفاصيل سلسلة أسعار فعلية/v1/commodities/physical/series/{series_id}

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

المعلمات

  • series_idمطلوب

    استخدم معرّفًا ثابتًا يعيده الاكتشاف، مثل fuel-eia-usa-regular-gasoline أو worldbank-cmo-copper.

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

  • series_idسلسلة نصية

    معرّف ثابت يعيده اكتشاف السلاسل.

  • currencyسلسلة نصية

    عملة التسعير. تستخدم سلاسل الوقود الأمريكي والأسعار المرجعية الشهرية USD.

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

    الوحدة المنشورة والكمية التي يُحسب السعر على أساسها. يستخدم الوقود us_gallon. تستخدم الأسعار المرجعية الشهرية metric_ton أو kilogram أو barrel أو cubic_meter أو troy_ounce أو mmbtu أو dry_metric_ton_unit أو sheet. الكمية هي 1، باستثناء الخشب الرقائقي الذي يستخدم USD لكل 100 لوح. لا تُحوّل القيم.

  • unit_keyسلسلة نصية

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

  • attributionسلسلة نصية

    احتفظ بنسب البيانات إلى مصدرها الوارد في الاستجابة مع البيانات. المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

  • commodity / category / productسلاسل نصية

    تعريف السلعة والفئة والمنتج. تشمل الأمثلة gasoline / energy / regular-gasoline وcopper / metals / copper. يعيد الاكتشاف القيم الخاصة بكل سلسلة.

  • commodity_keyسلسلة نصية

    يسمّي commodity_key السلعة بالطريقة نفسها في الأسعار الفورية والآجلة وأسعار التوقعات والأسعار الفعلية، مثل gold أو crude-oil. ويحمل النفط الخام أيضاً benchmark (القيمة wti أو brent أو urals أو dubai)، وتحمل العقود الآجلة exchange_mic، وهو الرمز القياسي للبورصة.

  • areaسلسلة نصية

    يحدد area النطاق الإقليمي ويُحذف في السلاسل الوطنية.

  • countryسلسلة نصية

    يعني WLD معيارًا عالميًا. يعني EUU الاتحاد الأوروبي. تستخدم البلدان رموز ISO alpha-3. يستخدم الوقود الأمريكي الرمز USA للمتوسط الوطني.

  • price_typeسلسلة نصية

    يستخدم الوقود retail_average. تستخدم سلاسل EIA الفورية اليومية والسلاسل الشهرية international_benchmark، باستثناء التبغ الذي يستخدم import_unit_value.

  • basisسلسلة نصية

    يصف basis تعريف السعر ويُحذف عندما لا يقدمه المصدر.

  • frequencyسلسلة نصية

    يوميًا لأسعار EIA الفورية للنفط والغاز، وأسبوعيًا للوقود الأمريكي، وشهريًا للأسعار المرجعية من World Bank.

المرجع الكامل ‏←
GETالحصول على أحدث سعر فعلي/v1/commodities/physical/series/{series_id}/latest

اقرأ أحدث سعر متاح للوقود الأسبوعي أو للمؤشر المرجعي الشهري مع فترة الرصد.

المعلمات

  • series_idمطلوب

    استخدم معرّفًا ثابتًا يعيده الاكتشاف، مثل fuel-eia-usa-regular-gasoline أو worldbank-cmo-copper.

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

  • series_idسلسلة نصية

    معرّف ثابت يعيده اكتشاف السلاسل.

  • currencyسلسلة نصية

    عملة التسعير. تستخدم سلاسل الوقود الأمريكي والأسعار المرجعية الشهرية USD.

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

    الوحدة المنشورة والكمية التي يُحسب السعر على أساسها. يستخدم الوقود us_gallon. تستخدم الأسعار المرجعية الشهرية metric_ton أو kilogram أو barrel أو cubic_meter أو troy_ounce أو mmbtu أو dry_metric_ton_unit أو sheet. الكمية هي 1، باستثناء الخشب الرقائقي الذي يستخدم USD لكل 100 لوح. لا تُحوّل القيم.

  • unit_keyسلسلة نصية

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

  • attributionسلسلة نصية

    احتفظ بنسب البيانات إلى مصدرها الوارد في الاستجابة مع البيانات. المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

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

    تواريخ المشاهدة شاملة البداية والنهاية. يستخدم الوقود تاريخ مسح يوم الاثنين لكليهما. تمتد المشاهدة الشهرية على الشهر بأكمله، مثل 2026-09-01 إلى 2026-09-30.

  • priceسلسلة نصية لعدد عشري

    السعر المنشور بعملة السلسلة لكل عدد من الوحدات تحدده unit_quantity. اقرأه مع نوع سعر السلسلة وbasis.

  • published_onالتاريخ

    تاريخ النشر. يُحذف عندما لا يقدمه المصدر.

  • revisionعدد صحيح

    يبدأ من 1 ويزداد عندما يغيّر إصدار لاحق القيمة الخاصة بتلك الفترة.

المرجع الكامل ‏←
GETالحصول على سجل الأسعار الفعلية/v1/commodities/physical/series/{series_id}/observations

اقرأ تاريخ أسعار الوقود الأسبوعية أو السلع الشهرية مع الفترات والوحدات المنشورة والمراجعات.

المعلمات

  • series_idمطلوب

    استخدم معرّفًا ثابتًا يعيده الاكتشاف، مثل fuel-eia-usa-regular-gasoline أو worldbank-cmo-copper.

  • startاختياري

    تاريخ بداية مشمول. قدّم start وend معًا، أو احذفهما معًا.

  • endاختياري

    تاريخ نهاية غير مشمول، ويجب أن يكون لاحقًا لـ start. تُعاد المشاهدات التي تتداخل مع نطاق التواريخ.

  • limitاختياري

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

  • cursorاختياري

    استخدم next_cursor من الصفحة السابقة مع عوامل التصفية نفسها وlimit نفسه. تعني null عدم وجود صفحات أخرى.

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

  • series_idسلسلة نصية

    معرّف ثابت يعيده اكتشاف السلاسل.

  • currencyسلسلة نصية

    عملة التسعير. تستخدم سلاسل الوقود الأمريكي والأسعار المرجعية الشهرية USD.

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

    الوحدة المنشورة والكمية التي يُحسب السعر على أساسها. يستخدم الوقود us_gallon. تستخدم الأسعار المرجعية الشهرية metric_ton أو kilogram أو barrel أو cubic_meter أو troy_ounce أو mmbtu أو dry_metric_ton_unit أو sheet. الكمية هي 1، باستثناء الخشب الرقائقي الذي يستخدم USD لكل 100 لوح. لا تُحوّل القيم.

  • unit_keyسلسلة نصية

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

  • attributionسلسلة نصية

    احتفظ بنسب البيانات إلى مصدرها الوارد في الاستجابة مع البيانات. المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

  • observationsمصفوفة

    مشاهدات مرتبة من الأقدم إلى الأحدث. تتضمن كل منها period_start وperiod_end وprice كسلسلة نصية عشرية وrevision. الحقل published_on اختياري.

  • observations[].period_start / observations[].period_endالتواريخ

    تواريخ المشاهدة شاملة البداية والنهاية. يستخدم الوقود تاريخ مسح يوم الاثنين لكليهما. تمتد المشاهدة الشهرية على الشهر بأكمله، مثل 2026-09-01 إلى 2026-09-30.

  • observations[].priceسلسلة نصية لعدد عشري

    السعر المنشور بعملة السلسلة لكل عدد من الوحدات تحدده unit_quantity. اقرأه مع نوع سعر السلسلة وbasis.

  • observations[].published_onالتاريخ

    تاريخ النشر. يُحذف عندما لا يقدمه المصدر.

  • observations[].revisionعدد صحيح

    يبدأ من 1 ويزداد عندما يغيّر إصدار لاحق القيمة الخاصة بتلك الفترة.

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

    رمز متابعة لا يلزم تفسير بنيته الداخلية. تشير null إلى الصفحة الأخيرة.

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

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

استرجع تاريخاً كاملاً

اقرأ كل السجل صفحة بصفحة واحفظه في ملف واستأنف إذا توقف.

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

سحب يومي للبيانات

شغّل سكربتًا صغيرًا مرة في اليوم وأضف النتيجة إلى ملف CSV.

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

التغطية

المصادر

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

API لأسعار زيت النخيل

أسعار زيت النخيل الخام وعناقيد الثمار الطازجة من إندونيسيا وماليزيا.

استكشف API ‏←

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

70 سلسلة شهرية من Pink Sheet الخاصة بالبنك الدولي.

استكشف API ‏←

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

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

استكشف API ‏←

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

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

استكشف API ‏←

الأسعار

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

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

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

ما الذي تغطيه واجهة API لأسعار الغاز؟

متوسطات التجزئة للبنزين العادي وديزل الطرق السريعة رقم 2 في الولايات المتحدة وتسع مناطق.

كم يبلغ التاريخ المتاح؟

يبدأ البنزين العادي الأمريكي في 20 أغسطس 1990 والديزل الأمريكي في 21 مارس 1994. وتبدأ السلاسل الإقليمية لاحقاً، من 1992 للبنزين و1997 للديزل. وتبلّغ كل سلسلة عن coverage_start الخاص بها. استخدم نقطة نهاية observations لنافذة تواريخ.

كيف أختار منطقة؟

اكتشف السلاسل بالمعاملين commodity=gasoline أو commodity=diesel. اقرأ area وdescription، ثم استخدم series_id ذلك للتفاصيل أو لأحدث سعر أو للتاريخ.

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

استخدم واجهة API لأسعار الوقود للمتوسط الأمريكي، والساحل الشرقي (PADD 1)، ونيو إنجلاند (PADD 1A)، والأطلسي الأوسط (PADD 1B)، والأطلسي الأدنى (PADD 1C)، والغرب الأوسط (PADD 2)، وساحل الخليج (PADD 3)، والجبال الصخرية (PADD 4)، والساحل الغربي (PADD 5)، والساحل الغربي باستثناء كاليفورنيا. المصدر: U.S. Energy Information Administration