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

مرجع API للتجارة حسب المنتج

اقرأ صادرات دولة ووارداتها حسب منتج HS بمستوى 2 أو 4 أو 6 أرقام، صفًا لكل رمز وشهر واتجاه، مع اسم كل رمز.

نظرة عامة

GET /v1/trade/{country}/products

يُعيد GET /v1/trade/{country}/products تجارة السلع لدولة واحدة حسب المنتج: صف لكل رمز HS وشهر واتجاه، مع اسم الرمز. يحدد level العمق: 2 للفصول (الافتراضي)، و4 للبنود، و6 للبنود الفرعية. من دون start وend تكون الإجابة أحدث شهر محفوظ.

يحدّ partner الإجابة بشريك واحد، ويحدّ hs الإجابة بالرموز التي تبدأ بهذه الأرقام. استخدمه لمعرفة ما تبيعه دولة وما تشتريه. ولمنتج واحد مقابل كل شريك استخدم مسار المنتج.

حيث لا يقدّم مكتب الدولة نفسها إلا إجماليات الشركاء (كندا والمكسيك وأستراليا)، يُجيب مسار المنتجات عن الفصول من تقارير الدول الأخرى، ويحمل الوسم partner_reported، ويُعيد 404 basis_not_available للبنود والبنود الفرعية. أداة MCP هي trade_get_products وتأخذ المعلمات نفسها.

طلب

أكبر ثلاثة فصول تصدير للمملكة المتحدة في يونيو 2026 مع حصتها، والاستجابة الفعلية:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?start=2026-06&end=2026-06&flow=export&top=3&share=true"
المملكة المتحدة، أكبر ثلاثة فصول تصدير
{
  "country": "GBR",
  "basis": "own",
  "source": "HM Revenue & Customs",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "GBP",
  "classification": "HS",
  "edition": "2022",
  "edition_basis": "inferred_from_year",
  "valuation_basis": "not_stated",
  "trade_system": "not_stated",
  "partner_basis": "not_stated",
  "trade_scope": "all_partners",
  "latest_period": "2026-09",
  "total_basis": "customs",
  "totals": [
    {
      "period": "2026-06",
      "flow": "export",
      "official_total": "37649508686",
      "sum_of_rows": "37649508686"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows",
    "rank",
    "share"
  ],
  "total": 3,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7115661421",
      "net_weight_kg": "195511199",
      "rank": 1,
      "share": "0.188997",
      "change": null,
      "product_code": "84",
      "product_level": 2,
      "product_label": "NUCLEAR REACTORS, BOILERS, MACHINERY AND MECHANICAL APPLIANCES; PARTS THEREOF",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "7044982137",
      "net_weight_kg": "1706268",
      "rank": 2,
      "share": "0.187120",
      "change": null,
      "product_code": "71",
      "product_level": 2,
      "product_label": "NATURAL OR CULTURED PEARLS, PRECIOUS OR SEMI-PRECIOUS STONES, PRECIOUS METALS, METALS CLAD WITH PRECIOUS METAL, AND ARTICLES THEREOF; IMITATION JEWELLERY; COIN",
      "edition": "2022"
    }
  ],
  "next_cursor": null
}

تعرض الصفحة أول صفين من الصفوف الثلاثة. share كسر من 1: الفصل 84 يمثّل 0.189134 من صادرات الشهر. partner هو null لأن الصفوف غير محصورة بشريك واحد.

المعلمات

معلمةالموضعالنوعمطلوبالافتراضيالقيم المسموح بها ومعناها
countryمسارسلسلة نصيةنعملا شيءرمز ISO 3166-1 alpha-3 للدولة المُبلِّغة، بأحرف كبيرة، مثل GBR. الرمز الذي لا يعود لدولة يُعيد 400. الدولة التي لا أرقام لها تُعيد 404 country_not_covered.
levelاستعلامعدد صحيحلا22 (الفصول) أو 4 (البنود) أو 6 (البنود الفرعية). أي قيمة أخرى تُعيد 400. بيانات تايلاند محفوظة بـ 4 أرقام، لذا تُعيد القيمة 6 لتايلاند 404 basis_not_available.
partnerاستعلامسلسلة نصيةلاكل الشركاءالتجارة مع هذا الشريك فقط (ISO 3166-1 alpha-3، بأحرف كبيرة). الرمز الذي ليس شريكًا للدولة يُعيد 400 unknown_partner.
flowاستعلامسلسلة نصيةلاالاتجاهانexport أو import.
startاستعلامسلسلة نصية، YYYY-MMلاأحدث شهر محفوظأول شهر، شاملًا. مع start ومن دون end تمتد الإجابة إلى أحدث شهر محفوظ. start بعد end يُعيد 400.
endاستعلامسلسلة نصية، YYYY-MMلاأحدث شهر محفوظآخر شهر، شاملًا. مع end وحده تكون الإجابة أحدث شهر محفوظ في ذلك التاريخ أو قبله.
hsاستعلامسلسلة نصية، من 1 إلى 6 أرقاملاكل الرموزالرموز التي تبدأ بهذه الأرقام فقط. الأطول من level يُعيد 400.
basisاستعلامسلسلة نصيةلاأفضل مصدر محفوظown أو third_party أو partner_reported. يطلب مصدرًا واحدًا بالاسم ويتخطى الترتيب. المصدر الذي لا يحتفظ بشيء للسؤال يُعيد 404 basis_not_available.
currencyاستعلامسلسلة نصيةلاعملة المصدر نفسهUSD. يحوّل كل شهر بمتوسط سعره اليومي.
topاستعلامعدد صحيحلاكل الصفوفمن 1 إلى 1000. يُبقي N من أكبر صفوف المنتجات في كل شهر واتجاه، مرتبة بالقيمة وتُفَضّ حالات التعادل برمز المنتج، ويضيف rank إلى كل صف. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء.
shareاستعلاممنطقيلاfalsetrue يضيف share إلى كل صف: قيمته مقسومة على مجموع كل صفوف المنتجات في الشهر والاتجاه نفسيهما، ككسر من 1 بـ6 منازل عشرية. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء.
ytdاستعلاممنطقيلاfalsetrue يجمع من يناير إلى end (الافتراضي: أحدث شهر) من الأشهر المخزّنة، ويكون period_type هو year_to_date. أرسل end وليس start: مع start يُعيد الطلب 400. الشهر المفقود يُعيد 404 period_not_published. محسوب. لا يصلح لإجابات تقارير الشركاء.
changeاستعلاممنطقيلاfalsetrue يضيف change إلى كل صف: الشهر نفسه (أو منذ بداية العام) قبل سنة، مع الفرق وحالة الإصدار للطرفين. الشهر المفقود قبل سنة يُعيد 404 period_not_published. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء.
limitاستعلامعدد صحيحلا500من 1 إلى 1000. أكبر عدد من الصفوف في صفحة واحدة.
cursorاستعلامسلسلة نصيةلالا شيءقيمة next_cursor من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير.

الاستجابة

تحتوي الإجابة على حقول مسار الشركاء، المسرودة في تلك الصفحة، مع حقل إضافي واحد عن مرشّح الشريك.

حقلالمعنى
countryرمز ISO 3166-1 alpha-3 للدولة المُبلِّغة التي تخصها الإجابة.
partnerالشريك الذي تُحصر به الصفوف، وnull عند عدم إرسال partner.
basisالمصدر الذي أجاب: own أو third_party (UN Comtrade) أو partner_reported.
sourceالجهة الناشرة، مثل HM Revenue & Customs أو Eurostat Comext أو UN Comtrade أو Customs reports of other countries.
reporters_includedمع partner_reported: count وcountries للدول المُبلِّغة التي بُدّلت تقاريرها في الإجابة. null للمصادر الأخرى.
noteاقرأ هذا قبل استخدام الأرقام. يُضبط في إجابات تقارير الشركاء، وnull في غيرها.
coveragefull أو partial. إجابة تقارير الشركاء هي partial.
partner_coverageall عندما يُسرد كل الشركاء، وtop_n عندما ينشر الناشر أكبر شركائه وصفًا واحدًا للباقي. null لإجابات تقارير الشركاء.
scopegoods.
currencyرمز ISO 4217 لكل قيمة في الإجابة.
classificationHS، النظام المنسق.
editionإصدار HS (2007 أو 2012 أو 2017 أو 2022) عندما يغطي إصدار واحد كل الأشهر المطلوبة. null عندما تختلف الأشهر، ويسمّي كل صف إصداره.
edition_basisas_published عندما يذكر الناشر الإصدار، وinferred_from_year عندما استنتجته Narwhal من السنة.
valuation_basisكيف يقيّم الناشر التجارة، مثل FOB للصادرات وCIF للواردات. not_stated عندما لا يذكر ذلك.
trade_systemgeneral أو special حيث يذكر الناشر ذلك. not_stated خلاف ذلك.
partner_basisهل تُحسب الشركاء بحسب المنشأ أو الشحن أو الوجهة، كما يذكر الناشر. not_stated خلاف ذلك.
trade_scopeما تغطيه الأرقام، مثل all_partners أو extra_union_only أو intra_union_other_method.
latest_periodأحدث شهر تحتفظ به Narwhal لهذه الدولة وهذا المصدر.
total_basisأساس official_total: customs أو balance_of_payments أو eurostat_concept. null عندما لا يقدّم الناشر إجماليًا.
totalsعنصر لكل شهر واتجاه: period وflow وofficial_total (إجمالي السلع الذي ينشره الناشر نفسه، وnull عند عدم وجوده) وsum_of_rows (مجموع كل صفوف الشركاء في الشهر والاتجاه باستثناء صفوف المجموعات، محسوب). من دون hs يحتوي على إجمالي السلع الكامل للشهر، حتى عندما يحدّ partner الصفوف. ومع hs (وفي مسار المنتج الواحد) يحتوي على إجمالي ذلك المنتج بدلًا منه: يكون sum_of_rows مجموع صفوف الإجابة في كل الصفحات (صفوف partner المسمّى إن وُجد؛ ولا يقتطعه top ولا تقسيم الصفحات)، ويكون official_total null، لأن الناشر لا يطبع إجماليًا لمنتج واحد.
fxمع currency=USD، وفي إجابات تقارير الشركاء بأكثر من عملة: السعر المستخدم لكل شهر، مع period وfrom_currency وto_currency وrate وdays في المتوسط. null خلاف ذلك.
calculatedأسماء الحقول التي حسبتها Narwhal، مثل sum_of_rows وrank وshare وvalue أو official_total.
totalعدد الصفوف المتطابقة في كل الصفحات.
next_cursorمؤشر الصفحة التالية. null في الصفحة الأخيرة.

كل عنصر في rows هو رمز HS واحد في شهر واتجاه واحد.

حقلالمعنى
flowexport أو import.
periodالشهر، YYYY-MM. ومنذ بداية العام، آخر شهر فيه.
period_typemonth أو year_to_date.
period_start, period_endأول يوم وآخر يوم يغطيهما الصف، YYYY-MM-DD.
valueوحدات كاملة من currency، كسلسلة عشرية.
net_weight_kgالوزن الصافي بالكيلوغرام حيث يقدّمه الناشر. null خلاف ذلك.
rank, share, changeكما في مسار الشركاء: يُضبط مع top وshare وchange، وnull خلاف ذلك.
product_codeرمز HS، من 2 أو 4 أو 6 أرقام. السطر الخاص بالناشر الذي ليس منتج HS يحتفظ برمز الناشر، مثل 00 لمؤن السفن والشحنات الخاصة.
product_level2 للفصل، و4 للبند، و6 للبند الفرعي.
product_labelاسم الرمز. null لسطر ليس منتج HS.
editionإصدار HS لمصدر الشهر. null عندما تستخدم الدول المُبلِّغة إصدارات مختلفة.

أمثلة إضافية

البنود الفرعية لبند واحد

الرموز ذات الأرقام الستة تحت البند 8517 لصادرات المملكة المتحدة، الصفحة الأولى من خمس:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/products?level=6&hs=8517&start=2026-06&end=2026-06&flow=export&limit=5"
المملكة المتحدة، البنود الفرعية للبند 8517
{
  "country": "GBR",
  "basis": "own",
  "source": "HM Revenue & Customs",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "GBP",
  "classification": "HS",
  "edition": "2022",
  "edition_basis": "inferred_from_year",
  "valuation_basis": "not_stated",
  "trade_system": "not_stated",
  "partner_basis": "not_stated",
  "trade_scope": "all_partners",
  "latest_period": "2026-09",
  "total_basis": "customs",
  "totals": [
    {
      "period": "2026-06",
      "flow": "export",
      "official_total": null,
      "sum_of_rows": "427312411"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 9,
  "partner": null,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "2578425",
      "net_weight_kg": "12393",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851711",
      "product_level": 6,
      "product_label": "Line telephone sets with cordless handsets",
      "edition": "2022"
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "105530961",
      "net_weight_kg": "115108",
      "rank": null,
      "share": null,
      "change": null,
      "product_code": "851713",
      "product_level": 6,
      "product_label": "Smartphones for wireless networks",
      "edition": "2022"
    }
  ],
  "next_cursor": "eyJiIjoiY2hhbmdlPUZhbHNlfGNvdW50cnk9R0JSfGVuZD0yMDI2LTA2fGZsb3c9ZXhwb3J0fGhzPTg1MTd8bGV2ZWw9NnxzaGFyZT1GYWxzZXxzdGFydD0yMDI2LTA2fHl0ZD1GYWxzZSIsIm8iOjV9"
}

تعرض الصفحة أول صفين من الصفوف الخمسة. total هو 9، لذا يُضبط next_cursor. تحتوي totals على مجموع البنود الفرعية التسعة، ويكون official_total null.

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

لا يقدّم مكتب كندا نفسه المنتجات. الطلب الخاص بالبنود يُعيد 404 وهو مجاني:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/products?level=4&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"
كندا، البنود تحت الفصل 85
{
  "type": "https://narwhalapi.com/problems/basis-not-available",
  "title": "Basis not available",
  "status": 404,
  "detail": "Narwhal holds CAN's own partner totals only, not its products; UN Comtrade is held as partner totals only, not by product; partner-reported products are held at chapter level only (level=2). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "5dd0f449-8c1e-4354-9af6-d8a76a5eefdd"
}

المصادر

يُجيب مصدر واحد عن كل طلب، وهو أول مصدر لديه صفوف بهذا الترتيب: مكتب الجمارك أو الإحصاء التابع للدولة نفسها (basis هو own)، ثم إيداع الدولة نفسها لدى UN Comtrade (third_party، إجماليات الشركاء فقط)، ثم تقارير الدول الأخرى عنها مع تبديل الاتجاهين (partner_reported). كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب المنتج لا تحتفظ UN Comtrade بشيء، فيكون الترتيب own ثم partner_reported، ولا تصل partner_reported إلا إلى الفصول (من رقمين، 2). يطلب basis مصدرًا واحدًا بالاسم. تبيّن الحقول basis وsource وnote في الإجابة أي مصدر أجاب، ولا تُخلط المصادر أبدًا في إجابة واحدة. إجابة تقارير الشركاء قياس مختلف عن أرقام الدولة نفسها، وليست رقمًا رسميًا أبدًا. تعود سطور الناشر الخاصة التي ليست منتجات HS، مثل مؤن السفن والشحنات الخاصة، برمز الناشر (00 على مستوى الفصل، و999999 على مستوى البند الفرعي) مع product_label null. لا تعرف مسارات رموز HS (/v1/trade/hs-codes) هذه الرموز وتُعيد 404 لها. ويُجيب مسار المنتج الواحد (/v1/trade/{country}/products/{hs}) عنها مع صفوفها وproduct_label null.

العملة

القيم وحدات كاملة من العملة المذكورة في currency، مكتوبة كسلاسل عشرية. افتراضيًا تكون عملة النشر الخاصة بالمصدر، مثل GBP لهيئة الإيرادات والجمارك البريطانية (HM Revenue & Customs). يحوّل currency=USD كل شهر بمتوسط أسعار الصرف اليومية لذلك الشهر. يُسرد السعر المستخدم لكل شهر في fx، ويسمّي calculated الحقول المحوَّلة. الشهر بلا سعر يُعيد 404 rate_not_available. وإذا تعذّرت الإجابة من مصدر الأسعار يُعيد الطلب 503 upstream_unavailable. الإجابة التي هي بـUSD أصلًا تعود كما هي.

التصفح بالصفحات

يحدد limit أكبر عدد من الصفوف في صفحة واحدة، من 1 إلى 1000، وقيمته الافتراضية 500. عندما تتطابق صفوف أكثر، يحمل next_cursor مؤشر الصفحة التالية: أرسله كـcursor مع بقاء كل المعلمات الأخرى دون تغيير. المؤشر المأخوذ من طلب مختلف يُعيد 400 invalid_cursor. يعدّ total الصفوف المتطابقة في كل الصفحات. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة.

السعر

الطلب الذي يُعيد صفًا واحدًا على الأقل يُحتسب استدعاءً واحدًا، بسعر $2 لكل 1,000 استدعاء. وكل صفحة من إجابة طويلة تُحتسب استدعاءً واحدًا، أيًّا كانت قيمة limit. الإجابة بلا صفوف مجانية، وكذلك كل خطأ.

الأخطاء

تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_id. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء API والرصيد.

الحالةالرمزمتى يحدث
400invalid_queryمعلمة مفقودة أو بصيغة خاطئة أو خارج قيمها المسموح بها: مثل level=3، أو start=2026-13، أو start بعد end، أو إرسال ytd مع start، أو hs أطول من level، أو إرسال as_of أو version (تقدّم هذه المسارات ما هو محفوظ الآن). وكذلك عندما يُطلب top أو share أو ytd أو change من إجابة تقارير الشركاء.
400invalid_cursorالمؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك.
400unknown_partnerpartner ليس شريكًا للدولة في الأشهر المطلوبة، مثلًا ZZZ is not a partner of GBR.
400range_too_largeيغطي top أو share أو ytd أو change أكثر من 12 شهرًا، أو تغطي إجابة تقارير الشركاء أكثر من 12 شهرًا، أو تغطي إجابة المنتجات، بأي مستوى (2 أو 4 أو 6 أرقام)، أكثر من 12 شهرًا محفوظة من دون hs أو partner. يرفض الاستعلام المفتوح نافذة تتجاوز 12 شهرًا بالرمز invalid_query.
404country_not_coveredلا تحتفظ Narwhal بأي صفوف تجارة للدولة في أي مصدر.
404period_not_publishedالشهر المطلوب غير محفوظ (No trade rows for 2026-10.)، أو ينقص شهر يحتاجه ytd أو change.
404basis_not_availableالمصدر المطلوب، أو كل مصدر في الترتيب، لا يحتفظ بشيء للسؤال. يذكر detail السبب: مثلًا أن مكتب الدولة نفسها يوفر إجماليات الشركاء فقط دون المنتجات، أو أن إجابات تقارير الشركاء تصل إلى الفصول (من رقمين، 2) فقط، أو أن بيانات مكتب تايلاند نفسها محفوظة بـ 4 أرقام وطُلبت بـ 6. راجع مسار التغطية.
404rate_not_availableطُلب currency=USD ولا يوجد سعر صرف لأحد الأشهر.
503upstream_unavailableمصدر أسعار الصرف لا يستطيع الإجابة. يؤثر ذلك في currency=USD وفي إجابات تقارير الشركاء التي تحتاج إلى تحويل. حاول مرة أخرى بعد قليل.
503trade_data_unavailableتعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل.

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

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