API سلاسل الأسعار الفعلية

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

نقطة النهاية والطلب

نقطة نهاية REST

GET /v1/commodities/physical/series

طلب العقد

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series?commodity=gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

يستخدم MCP commodities_list_physical_series. تشترك REST وMCP في المخطط نفسه وحصة الحساب والتحقق من الحقوق وبنية تفاصيل الخطأ.

المعلمات

الاسم	مطلوب	النوع	المعنى
`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`	لا	الاستعلام · عدد صحيح, 1–500	الحد الأقصى للعناصر في كل صفحة. القيمة الافتراضية 100.
`cursor`	لا	استعلام · سلسلة نصية	استخدم next_cursor من الصفحة السابقة مع عوامل التصفية نفسها وlimit نفسه. تعني null عدم وجود صفحات أخرى.

المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

الاستجابة

مثال على العقد

{
  "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_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
}

حقل	النوع	مطلوب	المعنى
`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[].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[].area`	سلسلة نصية	لا	يحدد area النطاق الإقليمي ويُحذف في السلاسل الوطنية.
`series[].country`	سلسلة نصية	نعم	يعني WLD معيارًا عالميًا. يعني EUU الاتحاد الأوروبي. تستخدم البلدان رموز ISO alpha-3. يستخدم الوقود الأمريكي الرمز USA للمتوسط الوطني.
`series[].price_type`	سلسلة نصية	نعم	يستخدم الوقود retail_average. تستخدم سلاسل EIA الفورية اليومية والسلاسل الشهرية international_benchmark، باستثناء التبغ الذي يستخدم import_unit_value.
`series[].basis`	سلسلة نصية	لا	يصف basis تعريف السعر ويُحذف عندما لا يقدمه المصدر.
`series[].frequency`	سلسلة نصية	نعم	يوميًا لأسعار EIA الفورية للنفط والغاز، وأسبوعيًا للوقود الأمريكي، وشهريًا للأسعار المرجعية من World Bank.
`series[].description`	سلسلة نصية	نعم	تعريف السلسلة.
`series[].coverage_start / series[].coverage_end`	التواريخ	نعم	أول يوم في أقدم مشاهدة وآخر يوم في أحدث مشاهدة، وكلاهما مشمول. تبدأ بعض السلاسل لاحقًا أو تكون قد انتهت. لا تضمن حدود التواريخ سجلًا متصلًا دون فجوات.
`next_cursor`	سلسلة نصية أو null	نعم	رمز متابعة لا يلزم تفسير بنيته الداخلية. تشير null إلى الصفحة الأخيرة.

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

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

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

التغطية

20 سلسلة أسبوعية لوقود التجزئة في الولايات المتحدة: البنزين العادي وديزل الطرق No. 2، لكل منهما المتوسط الأمريكي وتسع مناطق. الأسعار بوحدة USD لكل غالون أمريكي. يبدأ سجل المتوسط الأمريكي في أغسطس 1990 للبنزين ومارس 1994 للديزل. تبدأ السلاسل الإقليمية لاحقًا. ينمو السجل كل أسبوع بعد مسح الاثنين. المصدر: U.S. Energy Information Administration. تغطي ثلاث سلاسل فورية يومية من EIA خام WTI في كوشينغ وخام برنت والغاز الطبيعي في هنري هاب، بوحدة USD لكل برميل أو لكل مليون Btu. تشمل التغطية الشهرية 70 سلسلة من World Bank للسلع الزراعية والزيوت والبذور الزيتية والمعادن والحبوب والطاقة والأسمدة ومنتجات الغابات والثروة الحيوانية والألبان. يعود السجل إلى 1960، مع بدايات أحدث لبعض السلاسل. يُضاف شهر جديد بعد كل نشر شهري، لكن قد تتأخر بعض السلاسل أو تكون قد انتهت. ينتهي الشعير والذرة الرفيعة في أغسطس 2020؛ وينتهي الروبيان المكسيكي في أكتوبر 2023. تحقق من coverage_end لكل سلسلة. جميع الأسعار بعملة USD وبالوحدات المنشورة. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet)، CC BY 4.0

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