واجهة API لواردات السلع

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

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

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

نقطة نهاية REST

GET /v1/economics/{country}/trade/imports

طلب نموذجي

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

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

ترسل REST product و classification كمعلمتي استعلام منفصلتين. ويضعهما MCP داخل product كائن:

معلمات التجارة المصفاة في MCP

{
  "country": "USA",
  "period": "2026-06",
  "partner": "CAN",
  "product": {
    "classification": "HS2022",
    "code": "27"
  }
}

المعلمات

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

الاسم	مطلوب	النوع	المعنى
`country`	نعم	المسار · ISO alpha-3	رمز دولة واحد مدعوم بأحرف كبيرة: AUS وCAN وDEU وFRA وGBR وJPN وMYS وNLD وSGP وUSA.
`period`	لا	الاستعلام · YYYY أو YYYY-MM	اتركه لأحدث إصدار مكتمل مقبول، أو مرر فترة واحدة دقيقة.
`partner`	لا	الاستعلام · ISO alpha-3	مقبول بموجب العقد، لكن إجماليات الشريك المصفاة غير منشورة في الإصدار التجريبي الحالي.
`product`	لا	الاستعلام · رقمان أو 4 أو 6 أرقام	رمز منتج HS. أرسله مع التصنيف.
`classification`	لا	الاستعلام · HSYYYY	إصدار النظام المنسق. زوّده مع product.

الاستجابة

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

{
  "country": "USA",
  "period": "2026-06",
  "flow": "import",
  "value": "275000000000",
  "currency": "USD",
  "coverage": "merchandise",
  "partner": null,
  "product": null,
  "released_on": "2026-08-04"
}

حقل	النوع	مطلوب	المعنى
`country`	سلسلة نصية	نعم	رمز الدولة المطلوب بالأحرف الكبيرة وفق ISO alpha-3.
`period`	سلسلة نصية	نعم	فترة الملاحظة الرسمية المعادة.
`flow`	"export" أو "import"	نعم	اتجاه تجارة البضائع الذي يحدده المسار.
`value`	سلسلة عشرية	نعم	القيمة النقدية للاتجاه المحدد.
`currency`	سلسلة ISO 4217	نعم	عملة القيمة النقدية.
`coverage`	"merchandise"	نعم	يؤكد أن تجارة الخدمات غير مشمولة.
`partner`	سلسلة ISO alpha-3 أو قيمة فارغة	لا	مرشح الشريك المطلوب عند وجوده. قد تكون القيمة null أو تُحذف للإجمالي العام غير المصفّى.
`product`	كائن أو قيمة فارغة	لا	تصنيف HS ورمز المنتج المطلوبان عند وجودهما. قد تكون القيمة null أو تُحذف للإجمالي العام غير المصفّى.
`released_on`	التاريخ	نعم	تاريخ النشر الرسمي، وليس وقت استرجاع 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 تقديم إصدار مقبول بأمان.

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

الحداثة

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

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

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

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

إجماليات واردات السلع الوطنية غير المصفاة متاحة للعامة للدول AUS وCAN وDEU وFRA وGBR وJPN وMYS وNLD وSGP وUSA. يقبل العقد مرشحات الشريك والمنتج، لكنها تعيد 404 حتى تُنشر الإجماليات المصفاة.

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

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