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

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

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

نقطة نهاية REST

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

طلب العقد

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/observations?start=2026-07-01&end=2026-10-01&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

المعلمات

الاسم	مطلوب	النوع	المعنى
`series_id`	نعم	مسار · سلسلة نصية	استخدم معرّفًا ثابتًا يعيده الاكتشاف، مثل fuel-eia-usa-regular-gasoline أو worldbank-cmo-copper.
`start`	لا	الاستعلام · YYYY-MM-DD	تاريخ بداية مشمول. قدّم start وend معًا، أو احذفهما معًا.
`end`	لا	الاستعلام · YYYY-MM-DD	تاريخ نهاية غير مشمول، ويجب أن يكون لاحقًا لـ start. تُعاد المشاهدات التي تتداخل مع نطاق التواريخ.
`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_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)",
  "observations": [
    {
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "price": "13543",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "price": "14326",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "price": "14474",
      "published_on": null,
      "revision": 1
    }
  ],
  "next_cursor": 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 لوح. لا تُحوّل القيم.
`attribution`	سلسلة نصية أو null	نعم	احتفظ بنسب البيانات إلى مصدرها الوارد في الاستجابة مع البيانات. المصدر: إدارة معلومات الطاقة الأمريكية. المصدر: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`observations`	مصفوفة	نعم	مشاهدات مرتبة من الأقدم إلى الأحدث. تتضمن كل منها period_start وperiod_end وprice كسلسلة نصية عشرية وpublished_on الذي يقبل null وrevision.
`observations[].period_start / observations[].period_end`	التواريخ	نعم	تواريخ المشاهدة شاملة البداية والنهاية. يستخدم الوقود تاريخ مسح يوم الاثنين لكليهما. تمتد المشاهدة الشهرية على الشهر بأكمله، مثل 2026-09-01 إلى 2026-09-30.
`observations[].price`	سلسلة نصية لعدد عشري	نعم	السعر المنشور بعملة السلسلة لكل عدد من الوحدات تحدده unit_quantity. اقرأه مع نوع سعر السلسلة وbasis.
`observations[].published_on`	تاريخ أو null	نعم	تاريخ النشر عند توفره. تُحفظ null عندما يكون التاريخ غير معروف.
`observations[].revision`	عدد صحيح	نعم	يبدأ من 1 ويزداد عندما يغيّر إصدار لاحق القيمة الخاصة بتلك الفترة.
`next_cursor`	سلسلة نصية أو null	نعم	رمز متابعة لا يلزم تفسير بنيته الداخلية. تشير null إلى الصفحة الأخيرة.

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

400 invalid_query, الرمز أو المنطقة أو نطاق التواريخ أو limit أو المحدد غير صالح.
400 invalid_cursor, المؤشر غير صالح أو لا يطابق عوامل تصفية الطلب.
400 cursor_expired, تغير إصدار البيانات. أعد بدء التصفح بالصفحات دون مؤشر.
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.