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

الحصول على أحدث رقم للقصة

لكل سلسلة نقطة نهاية خاصة بالدولة: /v1/economics/{country}/inflation و/cpi و/unemployment و/gdp-growth. وبدون المعامل period تعيد أحدث فترة. يطلب هذا الطلب التضخم في الولايات المتحدة.

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/USA/inflation"

{
  "country": "USA",
  "period": "2026-09",
  "year_over_year": "3.7",
  "month_over_month": "0.6",
  "year_to_date": "4.0",
  "released_on": "2026-10-14"
}

يحمل هذا الرد تاريخين لهما معنيان مختلفان. period هو الشهر المرجعي الذي يقيسه الرقم، 2026-09، أي سبتمبر. أما released_on فهو يوم صدور الرقم، 2026-10-14. القصة المرسلة في أكتوبر تقول إن الأسعار ارتفعت 3.7 بالمئة في العام المنتهي في سبتمبر. أما تاريخ الإصدار في أكتوبر فيعطي الشهر الخاطئ.

حقول النسب الثلاثة مقاييس منفصلة. year_over_year يساوي 3.7 وmonth_over_month يساوي 0.6 وyear_to_date يساوي 4.0، وكلها بالنسبة المئوية. اذكر في الجملة النسبة التي تقتبسها، لأن كل واحدة تجيب عن سؤال مختلف.

الاستدعاء نفسه للسلاسل الأخرى

يستخدم نمو الناتج المحلي الإجمالي ربعًا في period، لذا يعني 2026-Q3 الربع الثالث. استخدم quarter_over_quarter عند الكتابة عن النمو مقارنة بالربع السابق، وyear_over_year عند المقارنة بالربع نفسه قبل عام.

وضع الرقم الجديد بجانب الرقم السابق

يعرض كل إصدار في التقويم values[].previous، وهو الرقم الذي سيُقارَن به الإصدار الجديد. في يوم الإصدار يمكن للقصة أن تقتبس قيمة previous من التقويم والقيمة الجديدة من نقطة نهاية الدولة بعد النشر. تحقق من transformation في قيمة التقويم، مثل year_over_year، ليكون الرقمان من النوع نفسه.

إعداد موجز: إصدارات الأسبوع مع أحدث الأرقام

يطلب البرنامج النصي من التقويم بيانات الولايات المتحدة من 9 إلى 13 نوفمبر، ويطبع كل إصدار بتوقيت نيويورك، ثم يجلب أحدث أرقام التضخم والبطالة والناتج المحلي الإجمالي ويكتب الفترة المرجعية بالكلمات.

1. احصل على مفتاح API احصل على مفتاح API من صفحة التسجيل واحفظه في NARWHAL_API_KEY.
2. عرض إصدارات الأسبوع لا يعيد GET /v1/economics/calendar الإصدارات بترتيب زمني. يحتفظ البرنامج النصي بتلك التي لها وقت at، ويرتبها، ثم يحوّلها إلى timezone الخاص بالجهة الناشرة.
3. جلب أحدث رقم لكل سلسلة استدعاء واحد لكل سلسلة. تحوّل الدالة say القيمة 2026-09 إلى سبتمبر 2026 والقيمة 2026-Q3 إلى الربع الثالث من 2026، فتستخدم الجملة period ولا تستخدم شهر released_on أبدًا.
   Python، موجز أسبوعي للقصة

   import os
   from datetime import datetime
   from zoneinfo import ZoneInfo
   import requests
   
   API = "https://api.narwhalapi.com"
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   MONTHS = ["January", "February", "March", "April", "May", "June", "July",
             "August", "September", "October", "November", "December"]
   QUARTERS = {"Q1": "first", "Q2": "second", "Q3": "third", "Q4": "fourth"}
   
   
   def get(path, **params):
       r = requests.get(f"{API}/v1/economics/{path}", headers=HEADERS, params=params, timeout=10)
       r.raise_for_status()
       return r.json()
   
   
   def say(period):
       year, part = period.split("-")
       if part in QUARTERS:
           return f"the {QUARTERS[part]} quarter of {year}"
       return f"{MONTHS[int(part) - 1]} {year}"
   
   
   week = get("calendar", countries="USA", start_date="2026-11-09", end_date="2026-11-13", limit=100)
   for x in sorted((x for x in week["releases"] if "at" in x), key=lambda x: x["at"]):
       local = datetime.fromisoformat(x["at"].replace("Z", "+00:00")).astimezone(ZoneInfo(x["timezone"]))
       print(local.strftime("%a %d %b %H:%M"), x["name"], "|", x.get("period", "no period"))
   
   for series in ("inflation", "unemployment", "gdp-growth"):
       d = get(f"USA/{series}")
       figures = {k: v for k, v in d.items() if k not in ("country", "period", "released_on")}
       print(series, figures, "for", say(d["period"]), "released", d["released_on"])

Mon 09 Nov 10:00 Wholesale trade | 2026-09
Tue 10 Nov 08:30 Wages and earnings | 2026-10
Tue 10 Nov 08:30 Consumer prices | 2026-10
Thu 12 Nov 08:30 Jobless claims | 2026-11-07
Thu 12 Nov 12:00 Petroleum inventories | no period
Thu 12 Nov 14:00 Public finances | 2026-10
Fri 13 Nov 08:30 Producer prices | 2026-10
inflation {'year_over_year': '3.7', 'month_over_month': '0.6', 'year_to_date': '4.0'} for September 2026 released 2026-10-14
unemployment {'rate': '4.2'} for September 2026 released 2026-10-02
gdp-growth {'year_over_year': '2.1', 'quarter_over_quarter': '0.832'} for the third quarter of 2026 released 2026-10-29

يغطي إصدار أسعار المستهلك يوم الثلاثاء 10 نوفمبر الفترة 2026-10، فهو رقم أكتوبر. وإلى أن يصدر، يبقى أحدث رقم للتضخم هو رقم سبتمبر الذي released_on له 2026-10-14. وبعد نشره تعيد نقطة النهاية الفترة الجديدة دون أي تغيير في طلبك.

كتابة الفترة المرجعية بشكل صحيح

• خذ الشهر أو الربع من period ولا تأخذه من released_on أبدًا. صدر رقم التضخم في أكتوبر لكنه يصف سبتمبر.
• وضّح أي مقارنة تقتبسها: year_over_year أو month_over_month أو year_to_date أو quarter_over_quarter. اسم الحقل هو التسمية.
• استخدم released_on في عبارة مثل أرقام نُشرت في ذلك اليوم، ليرى القراء مدى حداثة الرقم.

لماذا تختلف فترة التقويم عن فترة أحدث رقم؟

period في التقويم هو الشهر الذي سيغطيه الإصدار، أما أحدث رقم فهو آخر إصدار نُشر بالفعل. في مخرجات الموجز يعرض التقويم أسعار المستهلك للفترة 2026-10 بينما تعيد نقطة نهاية التضخم 2026-09. تحقق من الاثنين قبل أن تكتب أن رقمًا ما هو الأحدث.

ما الفرق بين نقطتي النهاية inflation وcpi؟

تعيد /inflation معدلات التغير بالنسبة المئوية. وتعيد /cpi مستوى المؤشر في value والأساس في index_base. اقتبس المعدل في العنوان، ولا تقتبس مستوى المؤشر إلا عندما تتناول القصة المؤشر نفسه.

هل تنشر كل الدول البطالة لنوع الفترة نفسه؟

لا. أعادت الولايات المتحدة للبطالة الفترة 2026-09 وهي شهر، بينما أعادت ألمانيا 2026-Q2 وهي ربع سنة. اقرأ period لكل دولة قبل أن تقارن الأرقام في جملة واحدة.