مرجع واجهة API للتجارة
اقرأ تجارة السلع حسب الدولة الشريكة وحسب منتج HS، شهرًا بشهر، من مكتب الجمارك أو الإحصاء في كل دولة تحتفظ Narwhal ببيانات مكتبها، ومن UN Comtrade أو من تقارير الدول الأخرى لبقية الدول.
نظرة عامة
تُعيد واجهة API للتجارة تجارة السلع حسب الدولة الشريكة وحسب المنتج، شهرًا واحدًا في كل مرة. الصف الواحد هو اتجاه واحد، تصدير أو استيراد، في شهر واحد، مع شريك أو منتج وقيمة بوحدات كاملة من عملة ما. تتبع المنتجات النظام المنسق (HS) بمستويات 2 و4 و6 أرقام. يبدأ السجل التاريخي في يناير 2010 حيث ينشره المصدر. تغطي الواجهة السلع فقط.
تأتي الأرقام من مكتب الجمارك أو الإحصاء في الدولة المُبلِّغة حيث تحتفظ Narwhal ببياناته، ومن UN Comtrade أو تقارير الدول الأخرى لبقية الدول الـ181 في قائمة التغطية. تذكر كل إجابة المصدر الذي أنتجها. تجد أي الدول تُجيب من أي مصدر في صفحة دول التجارة.
تُجيب سبعة مسارات، كلها تحت /، وكل مسار منها أداة MCP أيضًا بالمعلمات نفسها والإجابة نفسها. يأخذ كل طلب المفتاح في ترويسة Authorization: Bearer، كما في بقية Narwhal.
المسارات
| المسار | أداة MCP | ما يُجيب عنه |
|---|---|---|
GET / | trade_ | صادرات وواردات دولة واحدة حسب الشريك. |
GET / | trade_ | صادرات وواردات دولة واحدة حسب منتج HS، بمستوى 2 أو 4 أو 6 أرقام. |
GET / | trade_ | تجارة دولة واحدة في رمز HS واحد مع كل شريك. |
GET / | trade_ | استعلام مفتوح عبر عدة دول مُبلِّغة وشركاء وفصول. |
GET / | trade_ | أي مصدر يُجيب عن كل دولة، والأشهر المحفوظة. مجاني. |
GET / | trade_ | ابحث في رموز HS أو اعرضها حسب الاسم أو المستوى أو الأصل. |
GET / | trade_ | رمز HS واحد مع أصله والرموز التابعة له. |
لكل مسار صفحته الخاصة التي تعرض كل معلمة، وطلبًا يعمل مع استجابته الفعلية، وكل خطأ.
المصادر
تأتي كل إجابة من مصدر واحد، يُذكر في basis وsource. الطلب بلا basis يأخذ أول مصدر بهذا الترتيب يحتوي على صفوف. لا تُخلط المصادر أبدًا في إجابة واحدة، ويطلب basis مصدرًا واحدًا بالاسم.
basis | المصدر | ما هو | يصل إلى |
|---|---|---|---|
own | مكتب الجمارك أو الإحصاء التابع للدولة نفسها | أرقام المكتب نفسه، بعملته هو، كما نشرها. | الشركاء، والمنتجات بمستويات 2 و4 و6 أرقام حيث يوفرها المكتب |
third_ | UN Comtrade | الإيداع الشهري للدولة نفسها لدى الأمم المتحدة، يُقدَّم مع ذكر المصدر. | إجماليات الشركاء فقط |
partner_ | تقارير الجمارك في الدول الأخرى | ما تُبلِّغ به الدول الأخرى عن الدولة، مع تبديل الاتجاهين: واردات الدول الأخرى منها هي صادراتها. قياس مختلف، وليس رقمًا رسميًا أبدًا. | الشركاء، والمنتجات من رقمين (2) |
كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب المنتج لا تحتفظ UN Comtrade بشيء، فيكون الترتيب own ثم partner_. إجابة تقارير الشركاء لا إجمالي رسمي لها، ولا تقبل top أو share أو ytd أو change، وتغطي 12 شهرًا على الأكثر. يعرض GET / الحقل answers_، وهو المصدر الذي يُجيب عن كل دولة اليوم.
أي دولة تُجيب من أي مصدر: دول التجارة.
العملة
القيم وحدات كاملة من العملة المذكورة في currency، كسلاسل عشرية. افتراضيًا تكون عملة النشر الخاصة بالمصدر. يحوّل currency=USD كل شهر بمتوسط أسعار الصرف اليومية لذلك الشهر، ويسرد السعر المستخدم لكل شهر في fx، ويسمّي الحقول المحوَّلة في calculated. يذكر مسار الاستعلام المفتوح العملة في كل صف، لأن الدول المُبلِّغة تنشر بعملات مختلفة.
التصفح بالصفحات
يحدد limit أكبر عدد من الصفوف في صفحة واحدة، من 1 إلى 1000. قيمته الافتراضية 500 في مسارات الشركاء والمنتجات والمنتج الواحد والاستعلام المفتوح، و100 في GET /. عندما تتطابق صفوف أكثر، يحمل next_ مؤشر الصفحة التالية: أرسله كـcursor مع بقاء كل المعلمات الأخرى دون تغيير. المؤشر المأخوذ من طلب مختلف يُعيد 400 invalid_. يعدّ total الصفوف المتطابقة في كل الصفحات. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة.
السعر
تكلّف استدعاءات التجارة $2 لكل 1,000 استدعاء. الطلب الذي يُعيد صفًا واحدًا على الأقل يُحتسب استدعاءً واحدًا، وكل صفحة من إجابة طويلة تُحتسب استدعاءً واحدًا. الإجابة بلا صفوف مجانية، وكل خطأ مجاني، ومسار التغطية مجاني. راجع الأسعار لمعرفة الرصيد وعمليات الشحن.
الأخطاء
تستخدم الأخطاء بنية تفاصيل الخطأ المشتركة مع request_. تسرد صفحة كل مسار الأخطاء التي يمكن أن يُعيدها. هذه هي الأخطاء كلها.
| الحالة | الرمز | متى يحدث |
|---|---|---|
401, 402, 429 | unauthorized, insufficient_credits, rate_limited | مفتاح مفقود أو غير صالح، أو رصيد أقل من سعر الاستدعاء، أو كثرة الطلبات في الدقيقة. راجع أخطاء API والرصيد. |
400 | invalid_query | معلمة مفقودة أو بصيغة خاطئة أو خارج قيمها المسموح بها: مثل start=2026-13، أو start بعد end، أو إرسال ytd مع start، أو إرسال as_ أو version (تقدّم هذه المسارات ما هو محفوظ الآن). وكذلك عندما يُطلب top أو share أو ytd أو change من إجابة تقارير الشركاء. |
400 | invalid_cursor | المؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك. |
400 | unknown_partner | partner ليس شريكًا للدولة في الأشهر المطلوبة، مثلًا ZZZ is not a partner of GBR. |
400 | range_too_large | يغطي top أو share أو ytd أو change أكثر من 12 شهرًا، أو تغطي إجابة تقارير الشركاء أكثر من 12 شهرًا، أو تغطي إجابة المنتجات، بأي مستوى (2 أو 4 أو 6 أرقام)، أكثر من 12 شهرًا محفوظة من دون hs أو partner. يرفض الاستعلام المفتوح نافذة تتجاوز 12 شهرًا بالرمز invalid_. |
404 | hs_code_not_found | لا يوجد هذا الرمز في إصدار HS. |
404 | country_not_covered | لا تحتفظ Narwhal بأي صفوف تجارة للدولة في أي مصدر. |
404 | period_not_published | الشهر المطلوب غير محفوظ (No trade rows for 2026-10.)، أو ينقص شهر يحتاجه ytd أو change. |
404 | basis_not_available | المصدر المطلوب، أو كل مصدر في الترتيب، لا يحتفظ بشيء للسؤال. يذكر detail السبب: مثلًا أن مكتب الدولة نفسها يوفر إجماليات الشركاء فقط دون المنتجات، أو أن إجابات تقارير الشركاء تصل إلى الفصول (من رقمين، 2) فقط، أو أن بيانات مكتب تايلاند نفسها محفوظة بـ 4 أرقام وطُلبت بـ 6. راجع مسار التغطية. |
404 | rate_not_available | طُلب currency=USD ولا يوجد سعر صرف لأحد الأشهر. |
503 | upstream_unavailable | مصدر أسعار الصرف لا يستطيع الإجابة. يؤثر ذلك في currency=USD وفي إجابات تقارير الشركاء التي تحتاج إلى تحويل. حاول مرة أخرى بعد قليل. |
503 | trade_data_unavailable | تعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل. |
أدوات MCP
كل مسار هو أداة MCP قائمة بذاتها، بالمعلمات نفسها والإجابة نفسها. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة، لذلك تنقّل بين الصفحات باستخدام cursor. الأدوات هي:
trade_ list_ hs_ codestrade_ get_ hs_ codetrade_ get_ coveragetrade_ get_ partnerstrade_ get_ productstrade_ get_ producttrade_ get_ flowsهل كانت هذه الصفحة مفيدة؟