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

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

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

نقطة نهاية REST

GET /v1/commodities/physical/series/{series_id}

طلب العقد

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-regular-gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

المعلمات

الاسم	مطلوب	النوع	المعنى
`series_id`	نعم	مسار · سلسلة نصية	استخدم معرّفًا ثابتًا يعيده الاكتشاف، مثل fuel-eia-usa-regular-gasoline أو worldbank-cmo-copper.

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

الاستجابة

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

{
  "series_id": "fuel-eia-usa-regular-gasoline",
  "commodity": "gasoline",
  "category": "energy",
  "product": "regular-gasoline",
  "market": "USA",
  "area": null,
  "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).",
  "publisher": "U.S. Energy Information Administration",
  "attribution": "Source: U.S. Energy Information Administration",
  "coverage_start": "2026-07-20",
  "coverage_end": "2026-10-05"
}

حقل	النوع	مطلوب	المعنى
`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 لوح. لا تُحوّل القيم.
`attribution`	سلسلة نصية أو null	نعم	احتفظ بنسب البيانات إلى مصدرها الوارد في الاستجابة مع البيانات. المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: 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. يعيد الاكتشاف القيم الخاصة بكل سلسلة.
`market / area`	سلسلة نصية / سلسلة نصية أو null	نعم	السوق الذي ينطبق عليه السعر والنطاق الإقليمي الاختياري. يشير WLD إلى سعر مرجعي عالمي، وEUU إلى الاتحاد الأوروبي، وتستخدم أسواق البلدان رموز ISO alpha-3. يستخدم الوقود الأمريكي USA، وتكون area بقيمة null للمتوسط الوطني.
`price_type / basis`	سلسلة نصية / سلسلة نصية أو null	نعم	يستخدم الوقود retail_average. تستخدم السلاسل الشهرية international_benchmark، باستثناء التبغ الذي يستخدم import_unit_value. يصف basis تعريف السعر عند توفره.
`frequency`	سلسلة نصية	نعم	weekly للوقود الأمريكي وmonthly للأسعار المرجعية للبنك الدولي.
`description / publisher`	سلاسل نصية	نعم	تعريف السلسلة والمؤسسة الناشرة.
`coverage_start / coverage_end`	التواريخ	نعم	أول يوم في أقدم مشاهدة وآخر يوم في أحدث مشاهدة، وكلاهما مشمول. تبدأ بعض السلاسل لاحقًا أو تكون قد انتهت. لا تضمن حدود التواريخ سجلًا متصلًا دون فجوات.

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

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

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

التغطية

20 سلسلة أسبوعية لأسعار التجزئة للوقود في الولايات المتحدة: البنزين العادي وديزل الطرق رقم 2، ولكل منهما متوسط الولايات المتحدة وتسع مناطق. الأسعار بوحدة USD لكل غالون أمريكي. يبدأ السجل في 20 يوليو 2026، وتُضاف إليه بيانات كل أسبوع بعد مسح يوم الاثنين. المصدر: إدارة معلومات الطاقة الأمريكية. تشمل التغطية الشهرية 70 سلسلة من البنك الدولي للسلع الزراعية اللينة والزيوت والبذور الزيتية والمعادن والحبوب والطاقة والأسمدة والمنتجات الحرجية والماشية ومنتجات الألبان. يعود السجل إلى عام 1960، مع بدايات لاحقة لبعض السلاسل. أحدث شهر متاح هو سبتمبر 2026، لكن بعض السلاسل قد تتأخر أو تكون قد انتهت. تنتهي سلسلتا الشعير والذرة الرفيعة في أغسطس 2020، وسلسلة الروبيان المكسيكي في أكتوبر 2023. تحقق من coverage_end لكل سلسلة. جميع الأسعار بوحدة USD وبالوحدات المنشورة. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

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