تصفّح التوثيق كاملًا

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

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

طلب

تصفح تقويم الإصدارات الاقتصادية ‏←

تستخدم العمليتان مفتاح Bearer الخاص بـ Narwhal. Each successful request costs one call on the Calendars API code, $2 per 1,000 calls. نظرة عامة على المنتج ‏←

عرض الإصدارات
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 يومًا.
limit / cursorحجم الصفحة 1–100، والافتراضي 100. تابع باستخدام next_cursor مع المرشحات دون تغيير.
release_id / version_idتستخدم تفاصيل الإصدار معرّف مسار UUID ومعرّف إصدار UUID اختياريًا.

release_id غير المعروف يعيد 404 not_found. المؤشر المشوّه أو المعدّل أو الذي لا يطابق المرشحات يعيد 400 invalid_cursor. المؤشر الأقدم من 30 دقيقة أو اللقطة غير المتاحة يعيد 409 cursor_expired. ابدأ من جديد دون المؤشر المنتهي.

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

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

200 OK
{
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "revision": 0,
      "country": "USA",
      "series_id": "usa-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York",
      "values": []
    }
  ],
  "next_cursor": null
}
حقلقاعدة
namename هو الاسم الإنجليزي الموحّد لدى Narwhal، ويُختار من قائمة مغلقة، مثل Producer prices أو Labour force survey. ولا يتضمن تواريخ.
series_idseries_id هو معرّف Narwhal الدائم للسلسلة، وتشترك فيه جميع الإصدارات، مثل tur-producer-prices. وهو معرّف نصي مختصر وليس UUID، لذا لا تقبله مسارات /v1/economics/series/*. ويُحذف عندما لا تكون السلسلة قد صُنفت بعد.
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.
period / valuesperiod هي الفترة التي يغطيها الإصدار، بمستوى التفصيل الذي توفره الجهة الناشرة: 2026-09 (شهر)، أو 2026-Q3 (ربع سنة)، أو 2018-04/2018-06 (نطاق متحرك)، أو 2026-09-12 (يوم أو أسبوع)، أو 2025 (سنة). يُحذف الحقل إذا لم تحدد الجهة الناشرة فترة. أما values فهو موجود دائمًا، ويكون فارغًا حتى تُنشر الأرقام؛ انظر القيم أدناه.
date_basisdate_basis is indicative when the date comes from a third-party calendar and not from the publisher. An indicative date can still move. It is absent when the publisher or the central bank set the date. The publisher's date always wins over the third-party calendar.
meetingmeeting is set on a central bank's policy meeting and holds the meeting's days from the bank's own calendar. kind is scheduled (the date is on the bank's calendar for the year), unscheduled or extraordinary. starts_on is the first day of a multi-day meeting, when the bank gives it, and ends_on is the last day, the day the decision is announced.
revision / version / observed_atتزداد revision كلما تغيرت تفاصيل الإصدار. وتكون 0 إذا لم يُعدّل الإصدار مطلقًا. يعيد GET /v1/economics/calendar/{release_id} أيضًا version، وهي النسخة غير القابلة للتغيير التي تُمرر لاحقًا بصفتها version_id، وobserved_at، وهو آخر وقت رصد فيه Narwhal الإصدار في تقويم الجهة الناشرة.

لا يظهر الحقل إلا إذا كانت له قيمة. لا تُدرج المقالات البحثية ومجموعات البيانات المكررة التي تضعها بعض الجهات الناشرة إلى جانب إصداراتها.

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

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

يُعبّر عن التوقيت بأحد الحقول at أو date أو between أو by في المستوى الأعلى. احتفظ بـ timezone والحدود المتاحة؛ فـ by موعد نهائي، لا وعد بالنشر في ذلك اليوم. observed_at هو آخر وقت رصد فيه Narwhal الإصدار في تقويم الجهة الناشرة.

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

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

Consensus, indicative dates and central bank meetings

Besides the publishers' own schedules, the calendar carries a third-party calendar. It adds a consensus forecast to figures, dates for releases the publishers do not list, and the days of central bank policy meetings. The publisher's date and figure always win over the third-party calendar.

This request returns the Bank Indonesia policy rate decision with a meeting object and a consensus on each rate, and a bank lending release whose date is indicative. Nothing is published yet, so actual is absent.

Policy rate meeting and indicative date
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=IDN&start_date=2026-11-18&end_date=2026-11-18" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "releases": [
    {
      "release_id": "7c9f64b5-bc4c-4875-9757-a5a3be9796dd",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "scheduled",
      "date": "2026-11-18",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "deposit_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5",
          "consensus": "5"
        },
        {
          "measure": "lending_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "6.5",
          "consensus": "6.75"
        },
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5.75",
          "consensus": "6"
        }
      ],
      "meeting": {
        "kind": "scheduled",
        "ends_on": "2026-11-18"
      }
    },
    {
      "release_id": "ff160cc0-f950-4bde-8f98-73dbb6ff6423",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-bank-lending",
      "name": "Bank lending",
      "topic": "money_credit",
      "family": "money",
      "period": "2026-10",
      "status": "scheduled",
      "date_basis": "indicative",
      "at": "2026-11-18T07:30:00Z",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "bank_credit_yoy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "13.26"
        }
      ]
    }
  ],
  "next_cursor": null
}

After a decision, a figure from the third-party calendar shows as provisional until the publisher's own release confirms it. This answer is the Bank Negara Malaysia decision of 5 November 2026.

Provisional figure
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=MYS&start_date=2026-11-05&end_date=2026-11-05" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "releases": [
    {
      "release_id": "007f2565-07af-43df-b778-0abef890689a",
      "revision": 1,
      "country": "MYS",
      "series_id": "mys-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "published",
      "date_basis": "indicative",
      "at": "2026-11-05T07:00:00Z",
      "timezone": "Asia/Kuala_Lumpur",
      "values": [
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "actual": "2.75",
          "previous": "2.75",
          "consensus": "2.75",
          "provisional": true
        }
      ]
    }
  ],
  "next_cursor": null
}

Treat date_basis: indicative and provisional as signs that a date or a figure can still change.

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

The calendar covers 114 countries as of 13 November 2026. Official release schedules from statistical offices and central banks come first. A third-party calendar adds countries and releases that the publishers do not list in a form Narwhal can read. A date that comes only from the third-party calendar carries date_basis indicative. Coverage varies by publisher and economic series; inclusion does not mean every indicator has a schedule. Filter the list request by country and date window to see the releases available in that snapshot.

Countries in the calendar · 114

AGO ALB ARE ARG ARM AUS AUT AZE BEL BGD BGR BHR BIH BLR BRA BWA CAN CHE CHL CHN COL CPV CRI CYP CZE DEU DNK DOM ECU EGY EMU ESP EST FIN FRA GBR GEO GHA GRC GTM HKG HRV HUN IDN IND IRL ISL ISR ITA JAM JOR JPN KAZ KEN KGZ KOR LBN LKA LSO LTU LUX LVA MAC MAR MDA MEX MKD MLT MNE MNG MOZ MUS MWI MYS NAM NGA NLD NOR NZL OMN PAK PER PHL PNG POL PRT PRY PSE ROU RUS RWA SAU SGP SLV SRB SUR SVK SVN SWE SWZ SYC THA TUN TUR TWN UGA UKR URY USA UZB VNM ZAF ZMB ZWE

Countries with a release calendar page · 114

An empty result means no releases are listed for that query in the snapshot. It does not guarantee that the publisher has no upcoming releases. Central bank meeting dates are served in this calendar as meeting. Public holidays, including bank holidays, and exchange closures are separate calendar datasets: see the public holidays reference و exchange closures reference (الإنجليزية).

القيم

Each release in the economic release calendar API includes a values array, empty until figures are published. Each value is a figure printed by the publisher: actual for the release's own period and previous for the period before. An actual that comes from a third-party calendar is marked provisional. Narwhal never computes these figures.

مثال للقيم المنشورة
{
  "values": [
    {
      "measure": "producer_price_change_mom",
      "unit": "percent",
      "transformation": "month_over_month",
      "actual": "0",
      "previous": "0.1",
      "previous_revised_from": "0.2"
    }
  ]
}
حقلقاعدة
measuremeasure يحدد الرقم داخل الإصدار، مثل producer_price_change_mom.
conceptيوضح concept ما الذي يقيسه الرقم، مثل gdp أو cpi، ولذلك يحمل الرقم نفسه المفهوم نفسه في كل بلد. اقرأه مع transformation وannualization لإجراء مقارنة بين أرقام متماثلة.
noticeيحتوي notice على شروط المصدر التي تفرض الجهة الناشرة عرضها عند كل وصول، مثل شروط البنك المركزي الأوروبي. اعرضها مع الإصدار. يُحذف الحقل إذا لم توجد شروط من هذا النوع.
periodلا يظهر period إلا عندما تغطي القيمة فترة تختلف عن period الخاص بالإصدار، كما في طلبات إعانة البطالة المستمرة التي تغطي الأسبوع السابق لأسبوع الإصدار نفسه.
unitunit هي percent (القيمة 1.2 تعني 1.2%)، أو index (مع index_base، مثل 2015=100)، أو thousands، أو currency، أو ratio (مثل نسبة الوظائف إلى المتقدمين)، أو balance (صافي رصيد المسح بالنقاط، لا بالنسبة المئوية).
currency / scaleلا يظهر الحقلان currency (رمز ISO 4217) وscale (units أو thousands أو millions أو hundred_millions أو billions) إلا عندما تكون قيمة unit هي currency. يستخدم الرقم مقياس الأعداد الذي تطبعه الجهة الناشرة.
transformationtransformation هي month_over_month، أو year_over_year، أو quarter_over_quarter، أو three_month_on_three_month، أو change (فرق في المستويات بوحدة الآلاف، مثل التغير في التوظيف). يُحذف الحقل عندما تكون القيمة مستوىً.
annualized / not_seasonally_adjustedannualized is true when the figure is at an annual rate, as with U.S. GDP growth. not_seasonally_adjusted is true when the figure is not seasonally adjusted. If annualized is absent, the figure is not annualized. If not_seasonally_adjusted is absent, the figure is seasonally adjusted, or, on a figure from a third-party calendar, the source does not say.
actual / previousactual هو رقم فترة الإصدار نفسه؛ وprevious هو رقم الفترة السابقة. تنشر الجهة الناشرة كليهما، ولا يحسبهما Narwhal مطلقًا. يُحذف أي رقم لم يرد في الإصدار؛ ثم يحمل الإصدار التالي قيمة actual السابقة بصفتها previous.
consensusconsensus is the expected figure for the period, from a third-party calendar. It is a forecast and not a published figure. It is absent when no forecast is known, and it can appear on a value whose actual the publisher printed.
provisionalprovisional is true when actual has not been confirmed by the publisher's own release. The figure comes from a third-party calendar and can change when the publisher publishes. It is absent otherwise.
previous_revised_fromprevious_revised_from هو الرقم السابق كما نُشر أول مرة، عندما يعدّل هذا الإصدار قيمة previous.
value_statusلا يظهر value_status إلا عند غياب actual: تشير pending_capture إلى الفترة بعد الوقت المجدول وحتى التقاط الرقم، وتشير unavailable إلى أن الإصدار نُشر أو أُلغي دون ذلك الرقم.

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

هل كانت هذه الصفحة مفيدة؟