جلب البيانات التاريخية API واستئناف التعبئة

الجلب التاريخي عبر الـ API

تقبل نقاط نهاية الملاحظات نطاق تواريخ وحدًّا لحجم الصفحة ومؤشر متابعة. تستخدم أسعار الصرف /v1/fx/rates/{base}/observations، ويستخدم CPI المسار /v1/economics/{country}/cpi/observations، وتستخدم شموع السلع /v1/commodities/spot/{commodity}/{currency}/bars. معاملات التاريخ هي start وend، أو start_date وend_date، بحسب نقطة النهاية. تتضمن كل استجابة next_cursor، وقيمته null في الصفحة الأخيرة.

1. إعداد مفتاح API الخاص بك احصل على مفتاح API مجاني واحفظه في متغير البيئة NARWHAL_API_KEY. يقرأ البرنامج النصي ذلك المتغير ويرسل المفتاح بصيغة Authorization: Bearer YOUR_KEY إلى https://api.narwhalapi.com.
2. حدد السلسلة ونطاق التواريخ يطلب المثال سعر USD/IDR من 1 نوفمبر 2025 إلى 23 أكتوبر 2026 مع ضبط limit على 100. أبقِ عوامل التصفية نفسها في كل صفحة عند إرسال المؤشر المُرجع من الاستجابة السابقة.
3. احفظ كل صفحة في ملف استخدم السكربت لإلحاق كل ملاحظة بالملف usd_idr.jsonl على شكل سطر JSON. يرسل طلبًا آخر ما دامت لـ next_cursor قيمة، ويتوقف عندما تصبح فارغة.
   Python: سنة من أسعار USD/IDR اليومية في ملف

   import json, os
   import requests
   
   H = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   params = {
       "currencies": "IDR",
       "start_date": "2025-11-01",
       "end_date": "2026-10-23",
       "limit": 100,
   }
   rows, pages, cursor = 0, 0, None
   with open("usd_idr.jsonl", "a") as out:
       while True:
           if cursor:
               params["cursor"] = (
                   cursor  # the cursor carries the filters; resend them unchanged
               )
           r = requests.get(
               "https://api.narwhalapi.com/v1/fx/rates/USD/observations",
               params=params,
               headers=H,
               timeout=15,
           )
           r.raise_for_status()
           body = r.json()
           for day in body["observations"]:
               out.write(json.dumps(day) + "\n")
               rows += 1
           pages += 1
           cursor = body.get("next_cursor")
           if not cursor:
               break
   print(pages, "pages,", rows, "days")

4. اقرأ التواريخ المُرجعة في نطاق 1 نوفمبر 2025 إلى 23 أكتوبر 2026 يطبع السكربت 3 pages, 249 days. اقرأ أول تاريخ مخزَّن إضافة إلى آخر تاريخ، لأن الاستجابة قد تبدأ بعد تاريخ البداية الذي طلبته.

يحتفظ السكربت بعدّادين منفصلين للصفحات والأيام. يكتب كل ملاحظة قبل أن يطلب الصفحة التالية، ثم يطبع المجاميع بعد انتهاء حلقة المؤشر. يُفتح الملف في وضع الإلحاق، ويحتوي كل سطر محفوظ على ملاحظة واحدة. يقرأ الطلب سلسلة IDR بعملة أساس USD.

تُحتسب كل صفحة طلبًا واحدًا من رصيدك، وللحسابات التي تستخدم رصيدًا مجانيًا حد قدره 50 طلبًا في الدقيقة. يحتاج جلب عدة سلاسل إلى فواصل بين الصفحات للبقاء تحت حد الدقيقة، حتى لو احتاجت كل سلسلة إلى بضع صفحات فقط.

تحمل الاستجابات الترويسة X-RateLimit-Remaining. إذا أعاد طلب صفحة الخطأ 429 rate_limit_exceeded، فاستخدم قيمة Retry-After قبل طلب صفحة أخرى. تعني الاستجابة 402 insufficient_credits أن رصيدك قد نفد، فأضف رصيدًا قبل المتابعة. تستخدم الأخطاء application/problem+json وتتضمن status وcode وdetail وrequest_id، فاقرأ رمز الخطأ لتقرر هل يمكن متابعة الجلب.

استخدام جدول بيانات أو سير عمل بدون كود

يكفي الاستيراد عبر Sheets لبضع مئات من الصفوف. ولعملية جلب لمرة واحدة يكون السكربت أبسط من سير عمل يمر على الصفحات في حلقة. استخدم طريقة الملف إذا أردت كتابة الملاحظات فور وصولها؛ فمثال Python يلحق الصفوف طوال عملية الجلب.

يمكن لـ n8n أو Make أو Zapier المرور على الصفحات بالمؤشر. يجب أن يرسل سير العمل مرشحات التاريخ والسلسلة نفسها مع كل مؤشر، ثم يتوقف عندما تكون next_cursor تساوي null. يمكن أن يبدأ تدفق مستمر بعملية جلب تاريخي ثم يتابع بـسحب البيانات اليومي.

اختر طريقة الجلب التاريخي

ماذا لو توقف الجلب في منتصفه؟

أعد التشغيل من آخر تاريخ خزّنته. يلحق السكربت أسطر JSON فور استلام الملاحظات، فتبقى الصفوف المكتوبة في الملف إذا توقفت المهمة. استخدم ذلك التاريخ المخزَّن نقطةً لاستئناف النطاق.

قد تنتهي صلاحية مؤشر محفوظ. إذا أعاد الطلب 409 cursor_expired، فأعد البدء بدون المؤشر واستأنف من آخر تاريخ مخزَّن. يحمل المؤشر عوامل التصفية الخاصة بنطاقه، فأبقِها دون تغيير أثناء المرور على صفحات ذلك النطاق.

كم صفًا يمكنني طلبه في الصفحة؟

اضبط limit حتى الحد الأقصى لنقطة النهاية: 366 لملاحظات أسعار الصرف، و1,000 لملاحظات البيانات الاقتصادية، و500 لشموع السلع، و100 للتقويم الاقتصادي. القيمة الافتراضية 100. يتحكم الحد في حجم الصفحة فقط، وعليك متابعة next_cursor حتى لا تتضمن الاستجابة صفحة تالية.

لماذا يبدأ الجلب بعد التاريخ الذي طلبته؟

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

مثال حسابي: USD/IDR من 1 نوفمبر 2025 إلى 23 أكتوبر 2026

اطلب USD/IDR مع بداية 1 نوفمبر 2025 ونهاية 23 أكتوبر 2026 وحد للصفحة قدره 100. اتبع كل مؤشر مُرجع بعوامل التصفية نفسها. في هذا النطاق تحتوي الاستجابة على 249 صفًا موزعة على 3 صفحات، فيستخدم الجلب 3 طلبات.

الصف الأول هو الاثنين 3 نوفمبر 2025 لأن 1 و2 نوفمبر 2025 يصادفان عطلة أسبوعية. سعر USD/IDR في 3 نوفمبر 2025 هو 16,710.3، وفي 23 أكتوبر 2026 هو 18,107.8.