تصفّح التوثيق كاملًا

مرجع API لمسار تغطية التجارة

اقرأ أي مصدر يُجيب عن مسارات التجارة لكل دولة، وما هو محفوظ، ومن أي شهر إلى أي شهر.

نظرة عامة

GET /v1/trade/coverage

يُعيد GET /v1/trade/coverage صفًا لكل دولة: من يُجيب عن مسار الشركاء ومسار المنتجات، والمصدر الذي يُجيب اليوم، وكل مصدر محفوظ، والأشهر المحفوظة. هو الإجابة الحية عن السؤال الذي تجيب عنه صفحة دول التجارة بصورة عامة.

استدعِه قبل أن تبني على دولة. answers_with هو المصدر الذي يُجيب منه اليوم طلب بلا basis، ويسرد tiers_held كل قيمة من basis لها صفوف. أرسل country لصف واحد، أو احذفه لكل الدول. الاستدعاء مجاني. أداة MCP هي trade_get_coverage وتأخذ المعلمة نفسها.

طلب

تغطية المملكة المتحدة، والاستجابة الفعلية:

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_with هو own) ويحتفظ بالمنتجات (products_tier هو own). first_period وlatest_period هما الشهران المحفوظان من ذلك المكتب.

المعلمات

معلمةالموضعالنوعمطلوبالافتراضيالقيم المسموح بها ومعناها
countryاستعلامسلسلة نصيةلاكل الدولرمز ISO 3166-1 alpha-3 واحد بأحرف كبيرة، أو EMU لمنطقة اليورو. عند حذفه تحتوي الإجابة على صف لكل دولة. الرمز الذي لا يعود لدولة يُعيد 400، والدولة التي لا صف لها تُعيد 404.

الاستجابة

تحتوي الإجابة على حقل واحد هو countries، وهو قائمة. لكل عنصر هذه الحقول.

حقلالمعنى
countryالدولة، أو EMU لمنطقة اليورو.
partners_tierمن يُجيب عن مسار الشركاء مما تحتفظ به Narwhal مباشرة: own، أي مكتب الجمارك أو الإحصاء التابع للدولة نفسها، أو partner_reported، أي تقارير الدول الأخرى مع تبديل الاتجاهين، عندما لا تحتفظ Narwhal بأرقام من مكتب الدولة نفسها.
partner_coverageall عندما يُسرد كل الشركاء، وtop_n عندما ينشر الناشر أكبر شركائه وصفًا واحدًا للباقي. null عندما يكون partners_tier هو partner_reported.
products_tierمن يُجيب عن مسار المنتجات: own، أو partner_reported عندما لا يكون للدولة ملفات منتجات خاصة بها. تحتفظ UN Comtrade بإجماليات الشركاء فقط، فلا تُجيب أبدًا بحسب المنتج.
answers_withالمصدر الذي يُجيب منه اليوم مساري الشركاء والمنتجات، بهذا الترتيب: مكتب الدولة نفسها (own)، ثم إيداعها لدى UN Comtrade (third_party)، ثم تقارير الدول الأخرى (partner_reported، وليست رقمًا رسميًا أبدًا). كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب الفصل لا تحتفظ UN Comtrade بشيء، لذلك يُجيب partner_reported. null ما دامت Narwhal لا تحتفظ بشيء للدولة.
tiers_heldكل مصدر لديه صفوف الآن: قيم basis التي تُجيب عن هذه الدولة.
first_periodأول شهر تحتفظ به Narwhal من مكتب الدولة نفسها. null إن لم يوجد.
latest_periodأحدث شهر تحتفظ به Narwhal من مكتب الدولة نفسها. null إن لم يوجد.
comtrade_latest_periodأحدث شهر أودعته الدولة لدى UN Comtrade. null إن لم يوجد.
third_party_latest_periodأحدث شهر تحتفظ به Narwhal من UN Comtrade للدولة. null إن لم يوجد.
comtrade_periodsعدد الأشهر التي أودعتها الدولة لدى UN Comtrade.
comtrade_latest_yearأحدث سنة أودعتها الدولة لدى UN Comtrade.
has_headlinetrue عندما تنشر الدولة إجماليًا رئيسيًا شهريًا لتجارة السلع.
has_servicestrue عندما تنشر الدولة تجارة الخدمات.
has_tariff_booktrue عندما يتوفر دليل التعرفة الوطنية.

أمثلة إضافية

دولة لا يقدّم مكتبها الخاص إلا إجماليات الشركاء

كندا، التي لا يقدّم مكتبها الخاص إلا إجماليات الشركاء:

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_tier هو own وproducts_tier هو partner_reported: يأتي شركاء كندا من هيئة الإحصاء الكندية (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_id. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء API والرصيد.

الحالةالرمزمتى يحدث
400invalid_querycountry ليس رمز دولة.
404country_not_coveredلا تحتفظ Narwhal بأي صفوف تجارة للدولة في أي مصدر.

أخطاء API والرصيد · مرجع واجهة API للتجارة · دول التجارة

هل كانت هذه الصفحة مفيدة؟