مرجع API لمسار تغطية التجارة
اقرأ أي مصدر يُجيب عن مسارات التجارة لكل دولة، وما هو محفوظ، ومن أي شهر إلى أي شهر.
نظرة عامة
GET /
يُعيد GET / صفًا لكل دولة: من يُجيب عن مسار الشركاء ومسار المنتجات، والمصدر الذي يُجيب اليوم، وكل مصدر محفوظ، والأشهر المحفوظة. هو الإجابة الحية عن السؤال الذي تجيب عنه صفحة دول التجارة بصورة عامة.
استدعِه قبل أن تبني على دولة. answers_ هو المصدر الذي يُجيب منه اليوم طلب بلا basis، ويسرد tiers_ كل قيمة من basis لها صفوف. أرسل country لصف واحد، أو احذفه لكل الدول. الاستدعاء مجاني. أداة MCP هي trade_ وتأخذ المعلمة نفسها.
طلب
تغطية المملكة المتحدة، والاستجابة الفعلية:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/coverage?country=GBR"{
"countries": [
{
"country": "GBR",
"partners_tier": "own",
"partner_coverage": "all",
"products_tier": "own",
"answers_with": "own",
"tiers_held": [
"own",
"partner_reported"
],
"first_period": "2010-01",
"latest_period": "2026-09",
"comtrade_latest_period": "2026-08",
"third_party_latest_period": null,
"comtrade_periods": 200,
"comtrade_latest_year": 2025,
"has_headline": true,
"has_services": true,
"has_tariff_book": true
}
]
}يُجيب مكتب المملكة المتحدة الخاص (answers_ هو own) ويحتفظ بالمنتجات (products_ هو own). first_ وlatest_ هما الشهران المحفوظان من ذلك المكتب.
المعلمات
| معلمة | الموضع | النوع | مطلوب | الافتراضي | القيم المسموح بها ومعناها |
|---|---|---|---|---|---|
country | استعلام | سلسلة نصية | لا | كل الدول | رمز ISO 3166-1 alpha-3 واحد بأحرف كبيرة، أو EMU لمنطقة اليورو. عند حذفه تحتوي الإجابة على صف لكل دولة. الرمز الذي لا يعود لدولة يُعيد 400، والدولة التي لا صف لها تُعيد 404. |
الاستجابة
تحتوي الإجابة على حقل واحد هو countries، وهو قائمة. لكل عنصر هذه الحقول.
| حقل | المعنى |
|---|---|
country | الدولة، أو EMU لمنطقة اليورو. |
partners_ | من يُجيب عن مسار الشركاء مما تحتفظ به Narwhal مباشرة: own، أي مكتب الجمارك أو الإحصاء التابع للدولة نفسها، أو partner_، أي تقارير الدول الأخرى مع تبديل الاتجاهين، عندما لا تحتفظ Narwhal بأرقام من مكتب الدولة نفسها. |
partner_ | all عندما يُسرد كل الشركاء، وtop_ عندما ينشر الناشر أكبر شركائه وصفًا واحدًا للباقي. null عندما يكون partners_ هو partner_. |
products_ | من يُجيب عن مسار المنتجات: own، أو partner_ عندما لا يكون للدولة ملفات منتجات خاصة بها. تحتفظ UN Comtrade بإجماليات الشركاء فقط، فلا تُجيب أبدًا بحسب المنتج. |
answers_ | المصدر الذي يُجيب منه اليوم مساري الشركاء والمنتجات، بهذا الترتيب: مكتب الدولة نفسها (own)، ثم إيداعها لدى UN Comtrade (third_)، ثم تقارير الدول الأخرى (partner_، وليست رقمًا رسميًا أبدًا). كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب الفصل لا تحتفظ UN Comtrade بشيء، لذلك يُجيب partner_. null ما دامت Narwhal لا تحتفظ بشيء للدولة. |
tiers_ | كل مصدر لديه صفوف الآن: قيم basis التي تُجيب عن هذه الدولة. |
first_ | أول شهر تحتفظ به Narwhal من مكتب الدولة نفسها. null إن لم يوجد. |
latest_ | أحدث شهر تحتفظ به Narwhal من مكتب الدولة نفسها. null إن لم يوجد. |
comtrade_ | أحدث شهر أودعته الدولة لدى UN Comtrade. null إن لم يوجد. |
third_ | أحدث شهر تحتفظ به Narwhal من UN Comtrade للدولة. null إن لم يوجد. |
comtrade_ | عدد الأشهر التي أودعتها الدولة لدى UN Comtrade. |
comtrade_ | أحدث سنة أودعتها الدولة لدى UN Comtrade. |
has_ | true عندما تنشر الدولة إجماليًا رئيسيًا شهريًا لتجارة السلع. |
has_ | true عندما تنشر الدولة تجارة الخدمات. |
has_ | true عندما يتوفر دليل التعرفة الوطنية. |
أمثلة إضافية
دولة لا يقدّم مكتبها الخاص إلا إجماليات الشركاء
كندا، التي لا يقدّم مكتبها الخاص إلا إجماليات الشركاء:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/coverage?country=CAN"{
"countries": [
{
"country": "CAN",
"partners_tier": "own",
"partner_coverage": "top_n",
"products_tier": "partner_reported",
"answers_with": "own",
"tiers_held": [
"own",
"partner_reported"
],
"first_period": "2010-01",
"latest_period": "2026-09",
"comtrade_latest_period": "2026-08",
"third_party_latest_period": null,
"comtrade_periods": 200,
"comtrade_latest_year": 2025,
"has_headline": true,
"has_services": true,
"has_tariff_book": true
}
]
}partners_ هو own وproducts_ هو partner_: يأتي شركاء كندا من هيئة الإحصاء الكندية (Statistics Canada)، وتأتي منتجاتها حسب الفصل من تقارير الدول الأخرى.
دولة غير مغطاة
رمز دولة حقيقي بلا أرقام يُعيد 404 وهو مجاني:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/coverage?country=ATA"{
"type": "https://narwhalapi.com/problems/country-not-covered",
"title": "Country not covered",
"status": 404,
"detail": "ATA is not in the trade coverage list.",
"code": "country_not_covered",
"request_id": "c16523b6-7d27-4e1b-a2c3-f7e2acead523"
}المصادر
يُبلغ المسار عن المصادر ولا يختار أحدها. راجع صفحة دول التجارة لمعرفة ما هو كل مصدر ومتى يُجيب.
العملة
لا يُعيد المسار قيمًا، لذلك لا تنطبق أي عملة.
التصفح بالصفحات
لا يوجد تقسيم إلى صفحات في المسار. الطلب بلا country يُعيد كل الدول في إجابة واحدة.
السعر
هذا المسار مجاني. لا يُحتسب أي استدعاء، ويظل الحساب بحاجة إلى مفتاحه.
الأخطاء
تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء API والرصيد.
| الحالة | الرمز | متى يحدث |
|---|---|---|
400 | invalid_query | country ليس رمز دولة. |
404 | country_not_covered | لا تحتفظ Narwhal بأي صفوف تجارة للدولة في أي مصدر. |
هل كانت هذه الصفحة مفيدة؟