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

استرجع السلسلة الزمنية الحالية المقبولة لمؤشر أسعار المستهلك في دولة واحدة.

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

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

نقطة نهاية REST

GET /v1/economics/{country}/cpi/observations

طلب نموذجي

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

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

المعلمات

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

الاسم	مطلوب	النوع	المعنى
`country`	نعم	المسار · ISO alpha-3	رمز دولة واحد مدعوم بأحرف لاتينية كبيرة؛ راجع قائمة التغطية لهذه العملية.
`start`	لا	الاستعلام · YYYY-MM	أول فترة رصد، وهي مشمولة. في خطتَي Free وBasic، تُنقل البداية التي تسبق نافذة خطتك إلى أول فترة داخلها. وتتضمن الاستجابة عندئذٍ start.
`end`	لا	الاستعلام · YYYY-MM	آخر فترة رصد، وهي مشمولة في النتائج.
`limit`	لا	الاستعلام · عدد صحيح, 1–1000	الحد الأقصى لعدد الفترات المُعادة. القيمة الافتراضية 100. قد تحتوي الصفحة على فترات أقل؛ اتبع next_cursor.
`cursor`	لا	الاستعلام · سلسلة نصية غير قابلة للتفسير	قيمة next_cursor من الصفحة السابقة.

الاستجابة

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

{
  "country": "USA",
  "index_base": "1982-84=100",
  "as_of": "2026-08-12T00:00:00Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "333.918"
    }
  ],
  "next_cursor": null
}

حقل	النوع	مطلوب	المعنى
`country`	سلسلة نصية	نعم	رمز البلد المطلوب بأحرف كبيرة وفق ISO alpha-3. يُعاد مرة واحدة لكل صفحة، وليس مع كل مشاهدة.
`start`	سلسلة نصية	لا	يظهر فقط عندما تنقل خطتك start المطلوب إلى فترة لاحقة. لا تُعاد الفترات الأقدم.
`as_of`	طابع زمني وفق RFC 3339	لا	وقت آخر تحديث أجراه المصدر لأحدث مشاهدة في هذه الصفحة، بدقة الثواني الكاملة، وفق UTC.
`source`	كائن	لا	معلومات منشأ الإحصاء الوارد عبر موزّع؛ راجع عملية أحدث قيمة.
`index_base`	سلسلة نصية	نعم	فترة أساس المؤشر وقيمته الأساسية، مثل 1982-84=100. لا تضم الصفحة بيانات ذات أساسين مختلفين.
`observations`	مصفوفة	نعم	المشاهدات المعتمدة من الأقدم إلى الأحدث، مشاهدة واحدة لكل فترة. تُحذف قيم المصدر المفقودة ولا تُملأ أبدًا. قد تحتوي الصفحة على مشاهدات أقل من limit؛ اتبع next_cursor حتى تصبح قيمته null.
`observations[].period`	سلسلة نصية	نعم	الشهر أو الربع الرسمي الذي تمثله القراءة.
`observations[].value`	سلسلة نصية لعدد عشري	نعم	مستوى المؤشر المعتمد دون تحويل إلى فاصلة عائمة ثنائية.
`next_cursor`	سلسلة نصية أو null	نعم	مرّر هذه القيمة دون تغيير في cursor لقراءة الصفحة التالية؛ وتكون null في الصفحة الأخيرة.

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

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

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

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

يعيد هذا المسار سلسلة Narwhal المقبولة الحالية اعتباراً من as_of. إنه سجل وفق النسخة الحالية من البيانات، وليس إعادة بناء لكل نسخة نُشرت سابقًا.

قد تتضمن المصادر الرسمية قراءات متفرقة وتتيح بيانات تاريخية لفترات متفاوتة. ويحذف Narwhal القراءات المفقودة بدلًا من استيفائها أو ملئها بقيم سابقة.

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

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

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.