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

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

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

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

نقطة نهاية REST

GET /v1/economics/{country}/trade

طلب نموذجي

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

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

المعلمات

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

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

الاستجابة

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

{
  "country": "USA",
  "period": "2026-06",
  "exports": "189000000000",
  "imports": "275000000000",
  "balance": "-86000000000",
  "currency": "USD",
  "released_on": "2026-08-04"
}

حقل	النوع	مطلوب	المعنى
`country`	سلسلة نصية	نعم	رمز الدولة المطلوب بالأحرف الكبيرة وفق ISO alpha-3.
`period`	سلسلة نصية	نعم	فترة الرصد الرسمية المعادة.
`exports`	سلسلة نصية لعدد عشري غير سالب	نعم	إجمالي صادرات السلع.
`imports`	سلسلة نصية لعدد عشري غير سالب	نعم	إجمالي واردات السلع.
`balance`	سلسلة نصية لعدد عشري	نعم	الناتج الدقيق لطرح الواردات من الصادرات؛ وقد يكون سالبًا.
`currency`	سلسلة ISO 4217	نعم	العملة للقيم النقدية الثلاث كلها.
`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 هو تاريخ النشر الرسمي.

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

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

35 الدول

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, SAU, SGP, SVN, SWE, USA

تتبع الإجماليات الوطنية للسلع قائمة الدول أدناه. لا تشمل البيانات تجارة الخدمات.

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

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