واجهة API لسجل الناتج المحلي الإجمالي

استرجع السلسلة الزمنية الحالية المقبولة للناتج المحلي الإجمالي في دولة واحدة.

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

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

نقطة نهاية REST

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

طلب نموذجي

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

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

المعلمات

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

الاسم	مطلوب	النوع	المعنى
`country`	نعم	المسار · ISO alpha-3	رمز دولة واحد مدعوم بأحرف كبيرة: AUS وCAN وDEU وFRA وGBR وJPN وMYS وNLD وSGP وUSA.
`start`	لا	الاستعلام · YYYY-QN	فترة الملاحظة الأولى الشاملة.
`end`	لا	الاستعلام · YYYY-QN	فترة الملاحظة الأخيرة الشاملة.
`limit`	لا	الاستعلام · عدد صحيح, 1–1000	الحد الأقصى للملاحظات المعادة. الافتراضي 100.
`cursor`	لا	الاستعلام · سلسلة نصية غير قابلة للتفسير	قيمة next_cursor من الصفحة السابقة.

الاستجابة

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

{
  "observations": [
    {
      "country": "USA",
      "measure": "gdp",
      "value": "31000100000000",
      "unit": "USD",
      "transformation": "",
      "period": "2026-Q2"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T16:00:00Z"
}

حقل	النوع	مطلوب	المعنى
`observations`	مصفوفة	نعم	الملاحظات المقبولة من الأقدم إلى الأحدث. تُحذف قيم المصدر المفقودة ولا تُملأ مطلقًا.
`observations[].country`	سلسلة نصية	نعم	رمز الدولة المطلوب بالأحرف الكبيرة وفق ISO alpha-3.
`observations[].measure`	سلسلة نصية	نعم	المقياس الأساسي الذي تمثله هذه الملاحظة.
`observations[].period`	سلسلة نصية	نعم	الشهر أو الربع الرسمي الذي تمثله الملاحظة.
`observations[].value`	سلسلة عشرية	نعم	قيمة المصدر المقبولة من دون تحويل الفاصلة العائمة الثنائية.
`observations[].unit`	سلسلة نصية	نعم	وحدة المصدر أو رمز العملة للمقياس.
`observations[].transformation`	سلسلة نصية	نعم	تحويل المقياس، أو سلسلة فارغة للمستوى.
`next_cursor`	سلسلة نصية أو قيمة فارغة	لا	مرّر هذه القيمة دون تغيير في cursor لقراءة الصفحة التالية.
`as_of`	طابع وقت RFC 3339	لا	وقت قبول Narwhal للّقطة الحالية للسلسلة المخزنة.

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

400 invalid_query — تنسيق الدولة أو الفترة أو المرشح غير صالح.
401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
404 series_not_found — لا توجد ملاحظة معتمدة تطابق الطلب.
429 rate_limit_exceeded — تم بلوغ حد الشبكة أو الحساب قصير النافذة؛ أعد المحاولة بعد Retry-After.
429 quota_exhausted — بلغ الحساب مخصصه الشهري.
503 economics_unavailable — لا يستطيع Narwhal تقديم إصدار مقبول بأمان.

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

الحداثة

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

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

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

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

السجل الرسمي المتاح عام للدول AUS وCAN وDEU وFRA وGBR وJPN وMYS وNLD وSGP وUSA. وتختلف أول فترة متاحة حسب المصدر.

المسارات الإقليمية الإندونيسية وCommodities ليست عامة. وتتوفر FX عبر FX API.

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