تحميل أسعار المعادن CSV: سجل الأسعار التاريخي

تنزيل أشرطة الذهب اليومية عبر API

استخدم GET /v1/commodities/spot/XAU/USD/bars للذهب المسعّر بالدولار الأمريكي. يحتوي كل شريط على timestamp وعلى سلاسل عشرية للحقول open وhigh وlow وclose. يكتب النص البرمجي حقول الأسعار هذه مباشرة في ملف CSV ويأخذ التاريخ من الطابع الزمني. وتكون أعمدة المخرجات date وopen وhigh وlow وclose.

1. ضع مفتاح API في متغير البيئة احصل على مفتاح API مجاني واحفظه في متغير البيئة NARWHAL_API_KEY. يقرأ النص البرمجي هذا المتغير ويرسل المفتاح في ترويسة Authorization: Bearer YOUR_KEY.
2. تحديد التواريخ والفاصل الزمني start وend كلاهما طابعان زمنيان بصيغة ISO وهما مطلوبان. يستخدم المثال 2026-10-01T00:00:00Z حتى 2026-10-24T00:00:00Z مع ضبط interval على 1d، للحصول على أشرطة الذهب اليومية من 1 إلى 23 أكتوبر 2026.
3. احفظ النص البرمجي باسم bars.py حافظ على ترتيب رأس ملف CSV وحقول الأشرطة كما هو. يرسل النص البرمجي الطلبات إلى https://api.narwhalapi.com ويكتب الصفوف المعادة إلى مخرجات الإخراج القياسية، ولذلك يمكن للأمر في الخطوة التالية حفظها في ملف.
   Python، أشرطة الذهب اليومية إلى CSV (شغّله هكذا: python bars.py > gold.csv)

   import csv, os, sys
   import requests
   
   H = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   params = {
       "start": "2026-10-01T00:00:00Z",
       "end": "2026-10-24T00:00:00Z",
       "interval": "1d",
       "limit": 500,
   }
   out = csv.writer(sys.stdout)
   out.writerow(["date", "open", "high", "low", "close"])
   cursor = None
   while True:
       if cursor:
           params["cursor"] = cursor
       body = requests.get(
           "https://api.narwhalapi.com/v1/commodities/spot/XAU/USD/bars",
           params=params,
           headers=H,
           timeout=15,
       ).json()
       for b in body["bars"]:
           out.writerow([b["timestamp"][:10], b["open"], b["high"], b["low"], b["close"]])
       cursor = body.get("next_cursor")
       if not cursor:
           break
   

4. كتابة gold.csv استخدم python bars.py > gold.csv لكتابة ملف CSV. وفي الفترة من 1 إلى 23 أكتوبر 2026، تحتوي المخرجات على 17 صف بيانات يومي تحت رأس الأعمدة.

يُنشئ out.writerow الواقع قبل الحلقة رأس الأعمدة. وداخل الحلقة، يضيف كل استدعاء لـ out.writerow شريطًا بالترتيب الذي يحدده هذا الرأس. وتبقى حقول الأسعار سلاسل عشرية كما وردت في الاستجابة، ويوفّر b["timestamp"][:10] التاريخ. لاستخدام سعر الإغلاق اليومي في جدول بيانات أو نموذج، خذ قيمة close من صف التاريخ المطلوب. أما سعر الافتتاح والأعلى والأدنى لذلك الشريط فهي في الصف نفسه. وفي التصدير الساعي أو بالدقيقة، يظل هذا النص البرمجي يكتب جزء التاريخ فقط من كل طابع زمني.

استخدام جدول السجل أو الاستيراد إلى جدول بيانات

افتح سجل الأسعار في صفحة سلعة الذهب لاستخدام جدوله دون كتابة نص برمجي. ويمكن للحسابات المسجّلة الدخول أيضًا تنزيل السجل بصيغة CSV من صفحات السلع.

لإحضار ملف CSV الذي أنشأه النص البرمجي إلى Excel، استخدم Data > From Text/CSV. وفي Google Sheets استخدم File > Import. يحتوي الملف على التاريخ إلى جانب أسعار الافتتاح والأعلى والأدنى والإغلاق لكل شريط، ولذلك يمكنك استخدام السجل المصدَّر نفسه في جدول بيانات أو كمدخل لنموذج. احتفظ بعمود التاريخ مع الأسعار عند استيراد الصفوف.

اختيار طريقة التنزيل والفاصل الزمني

تقبل نقطة نهاية bars القيم 1m و1h و1d للمعامل interval. أبقِ على 1d للسجل اليومي. وللبيانات الساعية أو بالدقيقة، غيّر هذا المعامل وقلّص النافذة الزمنية المطلوبة؛ فتواريخ العيّنة ومثال CSV تصف أشرطة يومية.

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

لا توجد أشرطة للذهب الفوري عندما يكون السوق مغلقًا في عطلات نهاية الأسبوع. تمتد الفترة من 1 إلى 23 أكتوبر 2026 على 23 يومًا تقويميًا وتضم 17 شريطًا يوميًا، جميعها في أيام العمل. اقرأ التواريخ في ملف CSV على أنها تواريخ الأشرطة المعادة. ولا يضيف الفاصل اليومي صفوفًا لعطلات نهاية الأسبوع إلى الملف.

كم شريطًا يعود في كل طلب؟

يعيد كل طلب ما يصل إلى limit من الأشرطة، وهو 500 في النص البرمجي. تتبع الحلقة next_cursor إلى أن يصبح null، وتكتب أشرطة كل استجابة في ملف CSV نفسه. أبقِ هذه الحلقة كما هي عند تغيير التواريخ أو الفاصل الزمني، حتى يتضمن التصدير الصفحات التالية. وللنطاق الأطول، أبقِ على start وend وinterval بينما يحدد المؤشر الصفحة التالية. يضيف النص البرمجي هذا المؤشر إلى params قبل إرسال الطلب التالي. ويبقى الرأس خارج الحلقة، ولذلك تتشارك كل الصفحات مجموعة أسماء الأعمدة نفسها.

يعني الخطأ 409 cursor_expired أنك تحتاج إلى البدء من جديد دون مؤشر. ابدأ التصدير مرة أخرى بالقيمة cursor = None كما في بداية النص البرمجي، واكتب الملف من هذا الطلب الجديد.

ماذا لو كان تاريخ البداية قبل بداية السلسلة؟

يقرأ كل حساب السجل الكامل. اقرأ أول تاريخ مُرجَع لمعرفة أين يبدأ ملف CSV، لأن السلسلة قد تبدأ بعد تاريخ البداية في طلبك.

مثال تطبيقي: ذهب أكتوبر 2026

ابدأ بطلب العيّنة اليومي لشهر أكتوبر 2026. تبدأ التواريخ المعادة عند 2026-10-01 وتنتهي عند 2026-10-23، مع 17 صف بيانات. اكتب رأس ملف CSV، ثم اكتب تاريخ كل شريط وحقول أسعاره بترتيب ذلك الرأس. أول سعر إغلاق هو 4177.4458 في 1 أكتوبر 2026، ومكانه في عمود close من أول صف بيانات، بعد التاريخ وسعر الافتتاح والأعلى والأدنى.