واجهة API لمؤشر أسعار المستهلك (CPI)

استرجع مؤشر أسعار المستهلك العام لدولة واحدة وشهر واحد.

economics_get_cpi متاح عبر REST وعبر الأداة economics_get_cpi التابعة لـMCP. يعيد كلاهما بنية البيانات نفسها ويستهلك الحصة الشهرية نفسها.

نقطة النهاية والطلب

نقطة نهاية REST

GET /v1/economics/{country}/cpi

طلب نموذجي

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

يستخدم MCP أداة economics_get_cpi مع الوسيطات المقابلة أدناه.

المعلمات

تنسيق الفترة المقبول لهذه العملية هو YYYY-MM.

الاسم	مطلوب	النوع	المعنى
`country`	نعم	المسار · ISO alpha-3	رمز دولة واحد مدعوم بأحرف لاتينية كبيرة؛ راجع قائمة التغطية لهذه العملية.
`period`	لا	الاستعلام · YYYY-MM	لا تُرسله للحصول على أحدث إصدار مكتمل مقبول، أو حدّد فترة واحدة بعينها.
`version_id`	لا	الاستعلام · UUID	نسخة نشر غير قابلة للتغيير واختيارية. استخدم `resource_version` من حدث `dataset.published` أو `dataset.revised`؛ واحذفه لقراءة المؤشر المعتمد حاليًا.

الاستجابة

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

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "index_base": "1982-84=100",
  "released_on": "2026-08-12"
}

حقل	النوع	مطلوب	المعنى
`country`	سلسلة نصية	نعم	رمز الدولة المطلوب بالأحرف الكبيرة وفق ISO alpha-3.
`period`	سلسلة نصية	نعم	فترة الرصد الرسمية المعادة.
`value`	سلسلة نصية لعدد عشري موجب	نعم	مستوى المؤشر العام.
`index_base`	سلسلة نصية	نعم	فترة أساس المؤشر وقيمته الأساسية، مثل 1982-84=100.
`released_on`	التاريخ	نعم	تاريخ النشر الرسمي، وليس وقت استرجاع Narwhal.
`source`	كائن	لا	لا يظهر الكائن الاختياري `source` إلا عندما يرد الإحصاء عبر موزّع. ويتضمن `publisher` (الناشر الأصلي الذي يسميه الموزّع) و`distributor` (المؤسسة التي توزّع الإحصاء). عند وجود `source`، يكون `released_on` تاريخ نشر الموزّع، وليس تاريخ إصدار الناشر الأصلي. أما السلاسل الواردة مباشرة من الناشر فتحذف `source`.

الأخطاء والحصة

400 invalid_query — تنسيق الدولة أو الفترة أو المرشح غير صالح.
401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
403 plan_upgrade_required — تنتهي الفترة أو النطاق المطلوب قبل نافذة السجل في خطتك (Free لمدة 12 شهرًا، وBasic لمدة 5 سنوات).
404 series_not_found — لا توجد قراءة معتمدة تطابق الطلب.
429 rate_limit_exceeded — تم بلوغ حد الشبكة أو الحساب خلال الفترة الزمنية القصيرة؛ أعد المحاولة بعد المدة المحددة في Retry-After.
429 quota_exhausted — بلغ الحساب مخصصه الشهري.
503 economics_unavailable — لا يستطيع Narwhal تقديم إصدار مقبول بأمان.

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

حداثة البيانات

حذف period يعيد أحدث إصدار مقبول مخزن لدى Narwhal. يقرأ استدعاء API قاعدة بيانات Narwhal؛ ولا يتصل بالناشر الرسمي مباشرة.

released_on هو تاريخ النشر الرسمي.

اقرأ كيف تعمل فحوص المصدر والتحقق والإصدارات المخزنة والفحوص الفاشلة.

تغطية الإصدار التجريبي العام الحالي

34 الدول

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, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA

تشمل تغطية مؤشر أسعار المستهلك الوطني العام الدول المدرجة أدناه.

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

العودة إلى جميع عمليات Economics.