مواعيد صدور البيانات الاقتصادية: الوقت والفترة والقيمة السابقة

البحث عن إصدار واحد لبلد واحد

اطلب من التقويم بلدًا ويومًا بواسطة GET /v1/economics/calendar. يسأل هذا الطلب عن اليابان في 20 نوفمبر.

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/calendar?countries=JPN&start_date=2026-11-20&end_date=2026-11-20&limit=100"

{
  "releases": [
    {
      "release_id": "6c00d274-da35-4ed4-bcc1-574101544a03",
      "revision": 3,
      "country": "JPN",
      "series_id": "jpn-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-10",
      "status": "scheduled",
      "at": "2026-11-19T23:30:00Z",
      "timezone": "Asia/Tokyo",
      "values": [
        {
          "measure": "core_core_cpi_yoy",
          "concept": "cpi_ex_fresh_food_energy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.4",
          "not_seasonally_adjusted": true
        },
        {
          "measure": "core_cpi_yoy",
          "concept": "cpi_ex_fresh_food",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.1",
          "not_seasonally_adjusted": true
        },
        {
          "measure": "cpi_mom",
          "concept": "cpi",
          "unit": "percent",
          "transformation": "month_over_month",
          "previous": "0.4"
        },
        {
          "measure": "cpi_yoy",
          "concept": "cpi",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.1",
          "not_seasonally_adjusted": true
        }
      ]
    }
  ],
  "next_cursor": null
}

الإصدار هو أسعار المستهلك في اليابان بقيمة period تساوي 2026-10، أي أن الأرقام تغطي شهر أكتوبر. قيمة at هي 2026-11-19T23:30:00Z وقيمة timezone هي Asia/Tokyo. لكل عنصر في values قيمة measure وقيمة previous؛ والقيمة السابقة لـ cpi_yoy هي 2.1 ولـ cpi_mom هي 0.4. الأرقام نصوص، فحوّلها إلى أعداد قبل المقارنة.

يبيّن transformation كيف اشتُقّ الرقم: year_over_year لـ cpi_yoy وmonth_over_month لـ cpi_mom. ثلاثة من المقاييس الأربعة تحمل not_seasonally_adjusted: true، فتحقق من هذه الإشارة قبل أن تقارن توقعًا بالقيمة السابقة.

طلبنا 20 نوفمبر لكن at يقع في 19 نوفمبر بالتوقيت العالمي. فنافذة التاريخ تتبع التقويم المحلي للجهة الناشرة، والساعة 23:30 بالتوقيت العالمي هي 08:30 من صباح اليوم التالي في طوكيو.

اختيار الإصدارات القادمة عالية الاهتمام وتحويل الوقت

لا يحتوي التقويم على تصنيف للأهمية، فأنت من يقرر ما يُعدّ عالي الاهتمام. يستخدم السكربت أدناه قائمة مراقبة من قيم topic، ويُبقي الإصدارات التي ما زالت scheduled ولها وقت at، ويرتّبها ويأخذ الثلاثة الأولى.

1. ضبط قائمة المراقبة ومنطقتك الزمنية ضع المواضيع التي تتداولها في مجموعة. يراقب السكربت أسعار المستهلك والناتج المحلي الإجمالي والقوى العاملة والتوظيف والأجور، ويحوّل إلى America/New_York بوصفها المنطقة الزمنية للمتداول.
2. طلب النافذة الزمنية اطلب بلدًا واحدًا ونطاقًا من التواريخ. يستخدم السكربت اليابان من 16 إلى 29 نوفمبر مع limit يساوي 100.
3. التصفية والترتيب والتحويل تقرأ datetime.fromisoformat الطابع الزمني بالتوقيت العالمي، وتحوّله astimezone إلى المنطقة الزمنية للجهة الناشرة من الحقل timezone وإلى المنطقة الزمنية للمتداول. تأتي القيم السابقة من values[].previous.
   Python، الإصدارات الثلاثة المراقَبة التالية

   import os
   from datetime import datetime
   from zoneinfo import ZoneInfo
   import requests
   
   BASE = "https://api.narwhalapi.com"
   
   WATCH = {"consumer_prices", "gdp", "labour_force", "employment", "wages"}
   MY_TZ = ZoneInfo("America/New_York")
   
   r = requests.get(
       f"{BASE}/v1/economics/calendar",
       params={"countries": "JPN", "start_date": "2026-11-16", "end_date": "2026-11-29", "limit": 100},
       headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
       timeout=10,
   )
   r.raise_for_status()
   
   picked = [
       x for x in r.json()["releases"]
       if x.get("topic") in WATCH and x["status"] == "scheduled" and "at" in x
   ]
   for x in sorted(picked, key=lambda x: x["at"])[:3]:
       utc = datetime.fromisoformat(x["at"].replace("Z", "+00:00"))
       local = utc.astimezone(ZoneInfo(x["timezone"]))
       mine = utc.astimezone(MY_TZ)
       prev = ", ".join(f"{v['measure']} {v['previous']}" for v in x["values"] if "previous" in v)
       print(x["name"], x["period"])
       print("  UTC  ", utc.strftime("%a %d %b %H:%M"))
       print("  Tokyo", local.strftime("%a %d %b %H:%M"))
       print("  NYC  ", mine.strftime("%a %d %b %H:%M"))
       print("  previous:", prev or "none listed")

GDP 2026-Q3
  UTC   Sun 15 Nov 23:50
  Tokyo Mon 16 Nov 08:50
  NYC   Sun 15 Nov 18:50
  previous: none listed
Consumer prices 2026-10
  UTC   Thu 19 Nov 23:30
  Tokyo Fri 20 Nov 08:30
  NYC   Thu 19 Nov 18:30
  previous: core_core_cpi_yoy 2.4, core_cpi_yoy 2.1, cpi_mom 0.4, cpi_yoy 2.1
Wages and earnings 2026-09
  UTC   Tue 24 Nov 23:30
  Tokyo Wed 25 Nov 08:30
  NYC   Tue 24 Nov 18:30
  previous: average_cash_earnings_yoy 3.9, real_wages_yoy 1.6

يظهر صف الناتج المحلي الإجمالي بالتوقيت العالمي Sun 15 Nov 23:50 مع أن النافذة بدأت في 16 نوفمبر، لأنه 08:50 من يوم الاثنين 16 نوفمبر في طوكيو. ويظهر في سطر قيمته السابقة «none listed» لأن قائمة values في إصدار الناتج هذا فارغة. يطبع السكربت عنصرًا بديلًا كلما غابت previous، فلا يوقف رقم مفقود واحد الحلقة.

لحظة واحدة في ثلاث ساعات

طوكيو تسبق التوقيت العالمي بتسع ساعات، و23:30 زائد تسع ساعات هو 08:30 في اليوم التالي. أما نيويورك فتتأخر عنه بخمس ساعات في ذلك التاريخ، فيكون 23:30 ناقص خمس ساعات هو 18:30. يستخدم السكربت zoneinfo الذي يطبّق قواعد التوقيت الصيفي تلقائيًا، فلا حاجة إلى حفظ الفروق.

قراءة الإصدار نفسه لاحقًا

لكل إصدار release_id. يعيد GET /v1/economics/calendar/{release_id} ذلك الإصدار وحده مع حقلين إضافيين هما version وobserved_at، ويبيّن الأخير متى رأت Narwhal الإصدار آخر مرة في تقويم الجهة الناشرة. استخدمه لتحديث صف إصدار تراقبه دون تنزيل النافذة كلها.

تنتقل status من scheduled إلى published عند صدور الأرقام، وعندها قد تحمل القيمة actual بجانب previous. وللبعض الإصدارات stage أيضًا مثل flash أو advance أو preliminary أو final. اعرضه بجانب الاسم كي لا يُحسب التقدير الأول قيمةً نهائية.

هل يرتّب التقويم الإصدارات بحسب الأهمية؟

لا. تحمل الإصدارات قيمة family مثل prices أو labour أو gdp، وقيمة topic مثل consumer_prices، لكن لا تصنيف لها. ابنِ قائمة المراقبة من هذين الحقلين، واستخدم .get("topic") لأن بعض الإصدارات بلا موضوع.

لماذا لا تحتوي بعض الإصدارات على قيمة سابقة؟

values موجودة دائمًا لكنها قد تكون قائمة فارغة، وقد يفتقر مقياس ما إلى previous. وكانت قائمة إصدار الناتج المحلي الياباني أعلاه فارغة. وحين يراجع إصدار الرقم السابق تحمل previous_revised_from الرقم الذي استُبدل.

ماذا لو لم يكن للإصدار وقت محدد؟

ليس له at، وبدلًا من ذلك يحمل date أو between أو by، ويتخطاها السكربت لأنه يحتاج إلى طابع زمني للتحويل. وإن أردت هذه الصفوف أيضًا فاطبع date وضع علامة تفيد بأن الوقت مجهول بدل تخمين وقت.