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

الإصدارات الأحدث والقراءات التاريخية، مع توضيح التغطية حسب الدولة والمؤشر.

تُعيد سبعة مسارات أحدث إصدار رسمي معتمد. وتقابلها سبعة مسارات /observations تعيد السلسلة الزمنية المقبولة الحالية. تستخدم REST وMCP المخططات نفسها وتستهلكان الحصة الشهرية نفسها.

عنوان URL الأساسي والمعلمات

مسار REST الأساسي

https://api.narwhalapi.com/v1/economics/{country}

country هو رمز ISO alpha-3 مدعوم بالأحرف الكبيرة.
period اختياري. احذفه للإصدار الأحدث أو مرر تنسيق الشهر أو الربع أو السنة للعملية.
قد تُرجع نقاط نهاية الاقتصاد الأساسية مثل /v1/economics/{country}/cpi وأدوات MCP المطابقة لها تقديرات أولية غير نهائية للأرقام الرئيسية دون أن توضح الاستجابة أنها غير نهائية؛ وتستبدل Narwhal API هذه القيم عندما ينشر المصدر الأرقام النهائية.
يتطلب كل طلب ترويسة Bearer الموضحة في المصادقة.

اطلب فترة معروفة واحدة

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/cpi?period=2026-07" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

الدول

36 الدول

AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA

تختلف التغطية حسب العملية والدولة. تسرد كل عملية الدول المدعومة.

أحدث الإصدارات

افتح صفحة العملية للاطلاع على المعلمات الدقيقة وصيغ الفترات المقبولة وحقول الاستجابة والأمثلة والأخطاء والحداثة والحدود الحالية.

عملية	مسار REST	الفترة
مؤشر أسعار المستهلك	`/v1/economics/{country}/cpi`	`YYYY-MM`
التضخم	`/v1/economics/{country}/inflation`	`YYYY-MM`
البطالة	`/v1/economics/{country}/unemployment`	`YYYY, YYYY-MM, or YYYY-QN`
المشاركة في القوى العاملة	`/v1/economics/{country}/labour-force-participation`	`YYYY, YYYY-MM, or YYYY-QN`
الناتج المحلي الإجمالي	`/v1/economics/{country}/gdp`	`YYYY-QN`
نمو الناتج المحلي الإجمالي	`/v1/economics/{country}/gdp-growth`	`YYYY-QN`
تجارة السلع	`/v1/economics/{country}/trade`	`YYYY or YYYY-MM`

المشاهدات التاريخية

تقبل المسارات التاريخية start, end, limit، و cursor. تأتي النتائج من الأقدم إلى الأحدث، وتصف السلسلة المقبولة الحالية، وليس كل نسخة نُشرت سابقًا.

عملية	مسار REST	الفترة
سجل مؤشر أسعار المستهلك	`/v1/economics/{country}/cpi/observations`	`YYYY-MM`
سجل التضخم	`/v1/economics/{country}/inflation/observations`	`YYYY-MM`
سجل البطالة التاريخي	`/v1/economics/{country}/unemployment/observations`	`YYYY, YYYY-MM, or YYYY-QN`
سجل المشاركة في القوى العاملة	`/v1/economics/{country}/labour-force-participation/observations`	`YYYY, YYYY-MM, or YYYY-QN`
سجل الناتج المحلي الإجمالي	`/v1/economics/{country}/gdp/observations`	`YYYY-QN`
سجل نمو الناتج المحلي الإجمالي	`/v1/economics/{country}/gdp-growth/observations`	`YYYY-QN`
سجل تجارة السلع	`/v1/economics/{country}/trade/observations`	`YYYY-MM`

اصطلاحات الحقول

حقل أو قاعدة	المعنى
`country`	رمز الدولة المطلوب وفق ISO alpha-3.
`period`	الشهر أو الربع أو السنة الرسمية الدقيقة التي تمثلها الاستجابة.
`released_on`	تاريخ النشر الرسمي، وليس وقت استرجاع Narwhal.
سلاسل نصية لأعداد عشرية	القيم الاقتصادية الرقمية عبارة عن سلاسل نصية للحفاظ على التمثيل العشري الدقيق.
الوحدات والأسس	تُسمى حقول النسب المئوية بما يدل عليها. وتُذكر العملات وأسس المؤشرات. ولا تظهر علامة إلا عندما تكون السلسلة غير معدّلة موسميًا أو محوّلة إلى أساس سنوي.
الإصدارات المفقودة	يمتنع Narwhal عن تقديم البيانات عند تعذّر التحقق منها، بدلًا من اختلاق القيم المفقودة أو ملئها بقيم سابقة أو تحويلها إلى أصفار.

سجل السلسلة حسب المعرّف

يُرجع GET /v1/economics/series/{series_id}/observations سجل سلسلة واحدة حسب معرّفها. أداة MCP: ‏economics_read_series_observations. المعرّف هو UUID. لا تُقبل قيم series_id النصية المختصرة في تقويم الإصدارات الاقتصادية، مثل usa-new-home-sales، وتُرجع 400 invalid_query. تتوفر سلسلتان: مؤشر CPI الشهري الأسترالي (مثل 284aaefe-7919-4728-bc15-50879ba77211) وCPI ربع السنوي لنيوزيلندا.

تقبل start وend الاختياريتان YYYY أو YYYY-MM أو YYYY-MM-DD أو YYYY-QN. تتراوح limit بين 1–1000 (الافتراضي 100). مرر next_cursor بصفتها cursor للصفحة التالية. لا تقرأ خطتا Free وBasic إلا نافذة السجل الخاصة بهما؛ ويُرجع النطاق الأقدم 403 plan_upgrade_required. تُرجع السلسلة غير المعروفة 404 not_found.

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

{
  "country": "AUS",
  "series_id": "284aaefe-7919-4728-bc15-50879ba77211",
  "unit": "percent",
  "observations": [
    {
      "period": "2018-09",
      "value": "2",
      "released_on": "2025-10-29"
    },
    {
      "period": "2018-10",
      "value": "2.3",
      "released_on": "2025-10-29"
    }
  ],
  "next_cursor": null
}

توجد دائمًا country وseries_id وunit وobservations وnext_cursor. تكون next_cursor هي null في الصفحة الأخيرة. لكل رصد period وvalue وreleased_on. لا تظهر currency وsource إلا عند انطباقهما.

OpenAPI والاكتشاف

حدود الإصدار التجريبي العام الحالي

منحنيات عائد السندات الحكومية في الولايات المتحدة والمملكة المتحدة وألمانيا واليابان وكندا. استرجع بيانات تاريخ محدد أو سجلًا مقسمًا إلى صفحات عبر REST وMCP.

إندونيسيا والمسارات الإقليمية ليست ضمن الإصدار التجريبي العام لواجهة Economics.

راجع الأخطاء والحصة لسلوك السلسلة المفقودة وعدم توفر الخدمة.