مرجع API للإصدارات الاقتصادية

اعرض الإصدارات المجدولة واسترجع نسخ النشر غير القابلة للتغيير مع الحفاظ على دقة الجدول الأصلية.

طلب

تصفح تقويم الإصدارات الاقتصادية ‏← (الإنجليزية)

تستخدم العمليتان مفتاح Bearer الخاص بـ Narwhal. نظرة عامة على المنتج ‏←

عرض الإصدارات

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31&limit=25" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

GET /v1/economics/calendar/{release_id} يسترجع إصدارًا واحدًا. أضف version_id لاختيار إصدار محدد غير قابل للتغيير.

المعلمات

معلمة	قاعدة
`countries`	رموز ISO alpha-3 اختيارية. كرر معلمة الاستعلام لعدة دول؛ بحد أقصى 50.
`start_date / end_date`	نافذة تاريخ شاملة اختيارية. الإعداد الافتراضي من 30 يومًا قبل اليوم إلى 335 يومًا بعده؛ وبحد أقصى 366 يومًا.
`view`	تكون قيمة `view` إما `compact` (الافتراضية) للحصول على إدخال موجز لكل إصدار، أو `full` للحصول على الكائن نفسه الذي يعيده `GET /v1/economics/calendar/{release_id}`. ويتضمن العرض الكامل جميع الحقول: النسخة والتنقيح وتفاصيل الجدول الزمني والطوابع الزمنية للقيم والتعديل الموسمي والقيمة قبل التنقيح.
`limit / cursor`	حجم الصفحة 1–100، والافتراضي 100. تابع باستخدام `next_cursor` مع المرشحات دون تغيير.
`release_id / version_id`	تستخدم تفاصيل الإصدار معرّف مسار UUID ومعرّف إصدار UUID اختياريًا.

استجابة نموذجية

استجابة قائمة توضيحية. تعيد عملية التفاصيل كائن إصدار واحدًا بالحقول نفسها.

200 OK

{
  "status": "ok",
  "snapshot": "calendar-snapshot-20260914",
  "as_of": "2026-09-14T08:00:00Z",
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "series_id": "usa-consumer-prices",
      "country": "USA",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "title": "Consumer Price Index",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York"
    }
  ],
  "next_cursor": null
}

حقل	قاعدة
`title / name`	`title` هو العنوان الذي يستخدمه الناشر نفسه، بلغته وصياغته. أما `name` فهو الاسم الإنجليزي الموحد لدى Narwhal من قائمة مغلقة، مثل `Producer prices` أو `Labour force survey`، ولا يتضمن أي تواريخ.
`series_id`	`series_id` هو المعرّف الدائم الذي تمنحه Narwhal للسلسلة، وتشترك فيه جميع الطبعات، مثل `tur-producer-prices`. ولا يظهر إذا لم تُصنَّف السلسلة بعد.
`topic`	يحدد `topic` ما تقيسه السلسلة، وهو موحد بين الدول، مثل `consumer_prices` أو `labour_force` أو `gdp` أو `merchandise_trade` أو `policy_rate`. ولا يرد هذا الحقل إذا لم تُصنَّف السلسلة بعد، وقد تُضاف موضوعات جديدة.
`stage`	يحدد `stage` طبعة أرقام الفترة التي يتضمنها الإصدار: `flash` أو `advance` أو `first` أو `second` أو `third` أو `preliminary` أو `final`. ولا يظهر في الإصدار ذي الطبعة الواحدة.
`at / date / between / by`	يظهر حقل توقيت واحد بمجرد معرفة اليوم: `at` هو وقت الإصدار الدقيق، و`date` هو يوم الإصدار دون تحديد وقت، و`between` نطاق شامل للأيام المحتملة بصيغة `[from, to]`، أو `by` وهو آخر يوم ممكن، أي موعد نهائي لا يوم موعود. جميع الطوابع الزمنية بتوقيت UTC؛ و`timezone` هي المنطقة الزمنية IANA للناشر، وفي العرض الكامل يكون `schedule.local_date` يوم الإصدار في تلك المنطقة الزمنية.
`period / values`	`period` هي الفترة التي يغطيها الإصدار. ويظهر `values` بعد نشر الأرقام، ويتضمن `measure` و`unit` و`transformation` و`actual` و`previous`، إضافة إلى `currency` و`scale` للمبالغ المالية.

تعيد القائمة إدخالات موجزة افتراضيًا، ولا يظهر الحقل إلا إذا كانت له قيمة؛ مرّر view=full للحصول على جميع الحقول. ولا تُدرج المقالات البحثية ومجموعات البيانات المتكررة التي يدرجها بعض الناشرين بجانب إصداراتهم.

معنى الجدول والحالة

family هو أحد القيم التالية: gdp, prices, labour, trade, yield_curve, policy_rate, activity, survey, housing, money، أو public_finance. status هو scheduled, published، أو cancelled.

الجدول precision هو exact, date, estimated_range, deadline، أو unknown. احتفظ بالمنطقة الزمنية للمصدر والحدود المتاحة؛ فالموعد النهائي يمثل حدًا أقصى للتاريخ، وليس يوم نشر مضمونًا. observed_at و officially_published_at تصف أحداثًا مختلفة ويمكن أن تكون null.

يظل الإلغاء وإعادة الجدولة ممثّلَين بإصدارات صريحة. لا تستبدل وقتًا غير معروف بمنتصف الليل.

يستمد تقويم Narwhal تواريخ وأوقات إصدارات البنك المركزي الأوروبي وبنك كندا من موقعيهما الإلكترونيين، حيث تتاح مجانًا. ويتضمن كل إصدار للبنك المركزي الأوروبي في كل استجابة حقل notice الذي يذكر البنك المركزي الأوروبي مصدرًا ويوضح أن المعلومات متاحة مجانًا على https://www.ecb.europa.eu.

نطاق تغطية تقويم الإصدارات

تتوفر جداول إصدارات رسمية مختارة للدول أدناه. يختلف النطاق حسب الناشر والسلسلة الاقتصادية؛ ولا يعني الإدراج أن لكل مؤشر جدولًا. صفِّ طلب القائمة حسب الدولة ونافذة التاريخ لرؤية الإصدارات المتاحة في تلك اللقطة.

الدول التي تتوفر لها جداول إصدارات · 35

تعني النتيجة الفارغة عدم إدراج إصدارات لهذا الاستعلام في اللقطة. ولا تضمن أن الناشر لا يملك إصدارات قادمة. الإجازات الرسمية وإغلاقات البنوك مجموعتا تقويم منفصلتان.

القيم

يتضمن كل إصدار في واجهة برمجة تطبيقات تقويم الإصدارات الاقتصادية مصفوفة indicators. يحتوي كل مؤشر على رقم أوردته الجهة الناشرة: actual للفترة الخاصة بالإصدار وprevious للفترة السابقة لها. لا تحسب Narwhal هذه الأرقام مطلقًا. تصف الحقول أدناه فترة كل رقم ووحدته والتحويل المطبق عليه وما إذا كان معبّرًا عنه بمعدل سنوي.

حقل	قاعدة
`period / previous_period`	يحدد `period` الفترة التي يغطيها الرقم: شهرًا (`2026-08`)، أو ربع سنة (`2026-Q3`)، أو أسبوعًا ينتهي في تاريخ محدد (`2026-09-26`)، أو فترة متحركة من ثلاثة أشهر (`2026-06/2026-08`، الشهر الأول والأخير). يشير `previous_period` إلى الفترة السابقة مباشرةً بالتنسيق نفسه. في الإصدارات الأسبوعية، قد يغطي الرقم الأسبوع السابق للأسبوع الخاص بالإصدار، كما في طلبات إعانة البطالة المستمرة.
`unit`	تكون قيمة `unit` إحدى القيم التالية: `percent`، أو `index` (مع `index_base`، مثل `2015=100`)، أو `thousands`، أو `currency`، أو `ratio` (مثل نسبة الوظائف إلى المتقدمين)، أو `balance` (صافي الفرق في نتائج الاستطلاع بالنقاط، وليس نسبة مئوية).
`currency / scale`	لا يظهر الحقلان `currency` (رمز ISO 4217) و`scale` (`units` أو `thousands` أو `millions` أو `hundred_millions` أو `billions`) إلا عندما تكون قيمة `unit` هي `currency`. يستخدم الرقم مقياس الأعداد الذي تطبعه الجهة الناشرة.
`transformation`	تكون قيمة `transformation` إحدى القيم التالية: `level`، أو `month_over_month`، أو `year_over_year`، أو `quarter_over_quarter`، أو `three_month_on_three_month`، أو `change` (فرق بين المستويات، معبّر عنه بالآلاف، مثل التغير في التوظيف).
`annualization`	يظهر `annualization` دائمًا، وتكون قيمته `annualized` (مثل نمو الناتج المحلي الإجمالي الأمريكي معبّرًا عنه بمعدل سنوي) أو `not_annualized`.
`actual / previous`	`actual` هو الرقم الخاص بفترة الإصدار نفسه؛ و`previous` هو الرقم الخاص بالفترة السابقة لها. كلاهما توردُه الجهة الناشرة، ولا تحسبهما Narwhal مطلقًا. قد تكون قيمة `previous` هي `null` إذا لم يذكرها الإصدار؛ وعندئذ يتضمن الإصدار التالي قيمة `actual` السابقة بوصفها قيمة `previous` فيه.

قد تُضاف قيم جديدة لهذه الحقول بمرور الوقت، لذا ينبغي للتطبيقات العميلة قبول القيم التي لا تتعرف عليها.