مرجع API للتجارة حسب الشريك
اقرأ صادرات دولة ووارداتها حسب الدولة الشريكة، صفًا لكل شريك وشهر واتجاه، مع إجمالي الناشر نفسه بجانب مجموع الصفوف.
نظرة عامة
GET /
يُعيد GET / تجارة السلع لدولة واحدة حسب الشريك: صف لكل شريك وشهر واتجاه. من دون start وend تكون الإجابة أحدث شهر محفوظ.
استخدمه لمعرفة مع من تتاجر دولة وبأي حجم. للدولة نفسها حسب المنتج استخدم مسار المنتجات، ولمنتج واحد مقابل كل شريك استخدم مسار المنتج. ولمقارنة عدة دول في استدعاء واحد استخدم مسار الاستعلام المفتوح.
تسمّي كل إجابة المصدر الذي أنتجها في basis وsource، وتحمل إجمالي الناشر نفسه بجانب مجموع الصفوف في totals. مع hs تكون totals خاصة بذلك المنتج، ويكون official_ null. أداة MCP هي trade_ وتأخذ المعلمات نفسها.
طلب
أكبر ثلاثة شركاء تصدير للمملكة المتحدة في يونيو 2026، والاستجابة الفعلية:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/partners?start=2026-06&end=2026-06&flow=export&top=3"{
"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"
],
"total": 3,
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "5316654916",
"net_weight_kg": "76287894",
"rank": 1,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "4735227787",
"net_weight_kg": "341314142",
"rank": 2,
"share": null,
"change": null,
"partner": "USA",
"partner_label": "United States",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}تعرض الصفحة أول صفين من الصفوف الثلاثة. basis هو own، أي أن هيئة الإيرادات والجمارك البريطانية (HM Revenue & Customs) أجابت، وofficial_ يساوي sum_. وضُبط rank لأن top أُرسل، ويسرده calculated.
المعلمات
| معلمة | الموضع | النوع | مطلوب | الافتراضي | القيم المسموح بها ومعناها |
|---|---|---|---|---|---|
country | مسار | سلسلة نصية | نعم | لا شيء | رمز ISO 3166-1 alpha-3 للدولة المُبلِّغة، بأحرف كبيرة، مثل GBR. الرمز الذي لا يعود لدولة يُعيد 400. الدولة التي لا أرقام لها تُعيد 404 country_. |
partner | استعلام | سلسلة نصية | لا | كل الشركاء | رمز ISO 3166-1 alpha-3 لشريك واحد، بأحرف كبيرة. الرمز الذي ليس شريكًا للدولة يُعيد 400 unknown_. |
flow | استعلام | سلسلة نصية | لا | الاتجاهان | export أو import. |
start | استعلام | سلسلة نصية، YYYY-MM | لا | أحدث شهر محفوظ | أول شهر، شاملًا. مع start ومن دون end تمتد الإجابة إلى أحدث شهر محفوظ. start بعد end يُعيد 400. |
end | استعلام | سلسلة نصية، YYYY-MM | لا | أحدث شهر محفوظ | آخر شهر، شاملًا. مع end وحده تكون الإجابة أحدث شهر محفوظ في ذلك التاريخ أو قبله. |
hs | استعلام | سلسلة نصية | لا | كل المنتجات | تجارة هذا المنتج فقط، برمز من 2 أو 4 أو 6 أرقام (85 و8517 و851713): حصة كل شريك منها. الرمز بطول آخر يُعيد 400. بيانات تايلاند محفوظة بـ 4 أرقام، لذا يُعيد رمز من 6 أرقام لتايلاند 404 basis_. |
basis | استعلام | سلسلة نصية | لا | أفضل مصدر محفوظ | own أو third_ أو partner_. يطلب مصدرًا واحدًا بالاسم ويتخطى الترتيب. المصدر الذي لا يحتفظ بشيء للسؤال يُعيد 404 basis_. |
currency | استعلام | سلسلة نصية | لا | عملة المصدر نفسه | USD. يحوّل كل شهر بمتوسط سعره اليومي. |
top | استعلام | عدد صحيح | لا | كل الصفوف | من 1 إلى 1000. يُبقي N من أكبر صفوف الدول في كل شهر واتجاه، مرتبة بالقيمة وتُفَضّ حالات التعادل برمز الشريك، ويضيف rank إلى كل صف. لا تُرتَّب صفوف المجموعات والصفوف غير المخصصة. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء. |
share | استعلام | منطقي | لا | false | true يضيف share إلى كل صف: قيمته مقسومة على مجموع صفوف الدول في الشهر والاتجاه نفسيهما، ككسر من 1 بـ6 منازل عشرية. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء. |
ytd | استعلام | منطقي | لا | false | true يجمع من يناير إلى end (الافتراضي: أحدث شهر) من الأشهر المخزّنة، ويكون period_ هو year_. أرسل end وليس start: مع start يُعيد الطلب 400. الشهر المفقود يُعيد 404 period_. محسوب. لا يصلح لإجابات تقارير الشركاء. |
change | استعلام | منطقي | لا | false | true يضيف change إلى كل صف: الشهر نفسه (أو منذ بداية العام) قبل سنة، مع الفرق وحالة الإصدار للطرفين. الشهر المفقود قبل سنة يُعيد 404 period_. محسوب. يغطي 12 شهرًا على الأكثر. لا يصلح لإجابات تقارير الشركاء. |
include_ | استعلام | منطقي | لا | false | true يُعيد أيضًا صفوف المجموعات التي ينشرها الناشر، مثل الاتحاد الأوروبي أو ASEAN. لا يدخل صف المجموعة أبدًا في مجموع أو ترتيب أو حصة. |
limit | استعلام | عدد صحيح | لا | 500 | من 1 إلى 1000. أكبر عدد من الصفوف في صفحة واحدة. |
cursor | استعلام | سلسلة نصية | لا | لا شيء | قيمة next_ من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير. |
الاستجابة
تحتوي الإجابة على هذه الحقول. كل ما هو مشترك بين الصفوف يوجد هنا مرة واحدة.
| حقل | المعنى |
|---|---|
country | رمز ISO 3166-1 alpha-3 للدولة المُبلِّغة التي تخصها الإجابة. |
basis | المصدر الذي أجاب: own أو third_ (UN Comtrade) أو partner_. |
source | الجهة الناشرة، مثل HM Revenue & Customs أو Eurostat Comext أو UN Comtrade أو Customs reports of other countries. |
reporters_ | مع partner_: count وcountries للدول المُبلِّغة التي بُدّلت تقاريرها في الإجابة. null للمصادر الأخرى. |
note | اقرأ هذا قبل استخدام الأرقام. يُضبط في إجابات تقارير الشركاء، وnull في غيرها. |
coverage | full أو partial. إجابة تقارير الشركاء هي partial. |
partner_ | all عندما يُسرد كل الشركاء، وtop_ عندما ينشر الناشر أكبر شركائه وصفًا واحدًا للباقي. null لإجابات تقارير الشركاء. |
scope | goods. |
currency | رمز ISO 4217 لكل قيمة في الإجابة. |
classification | HS، النظام المنسق. |
edition | إصدار HS (2007 أو 2012 أو 2017 أو 2022) عندما يغطي إصدار واحد كل الأشهر المطلوبة. null عندما تختلف الأشهر، ويسمّي كل صف إصداره. |
edition_ | as_ عندما يذكر الناشر الإصدار، وinferred_ عندما استنتجته Narwhal من السنة. |
valuation_ | كيف يقيّم الناشر التجارة، مثل FOB للصادرات وCIF للواردات. not_ عندما لا يذكر ذلك. |
trade_ | general أو special حيث يذكر الناشر ذلك. not_ خلاف ذلك. |
partner_ | هل تُحسب الشركاء بحسب المنشأ أو الشحن أو الوجهة، كما يذكر الناشر. not_ خلاف ذلك. |
trade_ | ما تغطيه الأرقام، مثل all_ أو extra_ أو intra_. |
latest_ | أحدث شهر تحتفظ به Narwhal لهذه الدولة وهذا المصدر. |
total_ | أساس official_: customs أو balance_ أو eurostat_. null عندما لا يقدّم الناشر إجماليًا. |
totals | عنصر لكل شهر واتجاه: period وflow وofficial_ (إجمالي السلع الذي ينشره الناشر نفسه، وnull عند عدم وجوده) وsum_ (مجموع كل صفوف الشركاء في الشهر والاتجاه باستثناء صفوف المجموعات، محسوب). من دون hs يحتوي على إجمالي السلع الكامل للشهر، حتى عندما يحدّ partner الصفوف. ومع hs (وفي مسار المنتج الواحد) يحتوي على إجمالي ذلك المنتج بدلًا منه: يكون sum_ مجموع صفوف الإجابة في كل الصفحات (صفوف partner المسمّى إن وُجد؛ ولا يقتطعه top ولا تقسيم الصفحات)، ويكون official_ null، لأن الناشر لا يطبع إجماليًا لمنتج واحد. |
fx | مع currency=USD، وفي إجابات تقارير الشركاء بأكثر من عملة: السعر المستخدم لكل شهر، مع period وfrom_ وto_ وrate وdays في المتوسط. null خلاف ذلك. |
calculated | أسماء الحقول التي حسبتها Narwhal، مثل sum_ وrank وshare وvalue أو official_. |
total | عدد الصفوف المتطابقة في كل الصفحات. |
next_ | مؤشر الصفحة التالية. null في الصفحة الأخيرة. |
كل عنصر في rows هو شريك واحد في شهر واتجاه واحد.
| حقل | المعنى |
|---|---|
flow | export أو import. |
period | الشهر، YYYY-MM. ومنذ بداية العام، آخر شهر فيه. |
period_ | month أو year_. |
period_ | أول يوم وآخر يوم يغطيهما الصف، YYYY-MM-DD. |
value | وحدات كاملة من currency، كسلسلة عشرية. |
net_ | الوزن الصافي بالكيلوغرام، كسلسلة عشرية، حيث يقدّمه الناشر. null خلاف ذلك. |
rank | مع top: ترتيب الصف، 1 للأكبر. null خلاف ذلك. |
share | مع share: حصة الصف من الإجمالي ككسر، بـ6 منازل عشرية. null خلاف ذلك. |
change | مع change: كائن يحتوي على previous_ وprevious_ وabsolute (القيمة ناقص القيمة السابقة) وpercent (بالنسبة المئوية بـ4 منازل عشرية، وnull عندما كانت القيمة السابقة 0) وrelease_ وprevious_ (preliminary أو revised أو final، أو null عندما لا يذكر الناشر ذلك). null عندما لا يوجد الصف قبل سنة أو لم يُطلب change. |
partner | رمز ISO 3166-1 alpha-3 للشريك، أو رمز مجموعة مثل EUU، أو فارغ لسطر لا دولة له. |
partner_ | اسم الشريك كما يستخدمه الناشر نفسه. |
partner_ | country أو group أو unallocated. |
unallocated_ | لصف غير مخصص: not_ أو confidential أو stores_ أو free_ أو other أو rest. null خلاف ذلك. |
أمثلة إضافية
الاتجاهان لشريك واحد
ألمانيا والصين، من يناير إلى يونيو 2026، في الاتجاهين:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/DEU/partners?partner=CHN&start=2026-01&end=2026-06"{
"country": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "EUR",
"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": "eurostat_concept",
"totals": [
{
"period": "2026-01",
"flow": "export",
"official_total": "121792305000",
"sum_of_rows": "121792305000"
},
{
"period": "2026-01",
"flow": "import",
"official_total": "106754947046",
"sum_of_rows": "106754947046"
}
],
"fx": null,
"calculated": [
"sum_of_rows"
],
"total": 12,
"rows": [
{
"flow": "export",
"period": "2026-01",
"period_type": "month",
"period_start": "2026-01-01",
"period_end": "2026-01-31",
"value": "5559611667",
"net_weight_kg": "355538457",
"rank": null,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
},
{
"flow": "import",
"period": "2026-01",
"period_type": "month",
"period_start": "2026-01-01",
"period_end": "2026-01-31",
"value": "8853410701",
"net_weight_kg": "1020758294",
"rank": null,
"share": null,
"change": null,
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null
}
],
"next_cursor": null
}تعرض الصفحة أول صفين من 12 صفًا وأول عنصرين من 12 عنصرًا في totals. تُجاب ألمانيا من يوروستات (Eurostat Comext)، باليورو.
منتج لا يوفره مكتب الدولة نفسها
يوفر مكتب كندا نفسه إجماليات الشركاء فقط. الطلب الخاص بمنتج واحد يُعيد 404 وهو مجاني:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/CAN/partners?hs=8517&start=2026-06&end=2026-06&limit=3"{
"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 answers are held at chapter level only (hs of 2 digits). See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "ebc75b49-165e-44b4-841d-8f80dc308295"
}المصادر
يُجيب مصدر واحد عن كل طلب، وهو أول مصدر لديه صفوف بهذا الترتيب: مكتب الجمارك أو الإحصاء التابع للدولة نفسها (basis هو own)، ثم إيداع الدولة نفسها لدى UN Comtrade (third_، إجماليات الشركاء فقط)، ثم تقارير الدول الأخرى عنها مع تبديل الاتجاهين (partner_). كانت تقارير الدول الأخرى ستسبق UN Comtrade فقط عندما يكون لدى 200 دولة مُبلِّغة على الأقل صفوف عن الدولة، وهو أكثر مما تحتفظ به Narwhal، لذلك تأتي أخيرًا. بحسب المنتج لا تحتفظ UN Comtrade بشيء، فيكون الترتيب own ثم partner_، ولا تصل partner_ إلا إلى الفصول (من رقمين، 2). يطلب basis مصدرًا واحدًا بالاسم. تبيّن الحقول basis وsource وnote في الإجابة أي مصدر أجاب، ولا تُخلط المصادر أبدًا في إجابة واحدة. إجابة تقارير الشركاء قياس مختلف عن أرقام الدولة نفسها، وليست رقمًا رسميًا أبدًا. قد تكون قائمة الشركاء في مصدر ما قصيرة: عندما يكون partner_ هو top_ يسمّي الناشر أكبر شركائه وصفًا واحدًا للباقي، وتبقى الصفوف مجموعة إلى الإجمالي.
العملة
القيم وحدات كاملة من العملة المذكورة في currency، مكتوبة كسلاسل عشرية. افتراضيًا تكون عملة النشر الخاصة بالمصدر، مثل GBP لهيئة الإيرادات والجمارك البريطانية (HM Revenue & Customs). يحوّل currency=USD كل شهر بمتوسط أسعار الصرف اليومية لذلك الشهر. يُسرد السعر المستخدم لكل شهر في fx، ويسمّي calculated الحقول المحوَّلة. الشهر بلا سعر يُعيد 404 rate_. وإذا تعذّرت الإجابة من مصدر الأسعار يُعيد الطلب 503 upstream_. الإجابة التي هي بـUSD أصلًا تعود كما هي.
التصفح بالصفحات
يحدد limit أكبر عدد من الصفوف في صفحة واحدة، من 1 إلى 1000، وقيمته الافتراضية 500. عندما تتطابق صفوف أكثر، يحمل next_ مؤشر الصفحة التالية: أرسله كـcursor مع بقاء كل المعلمات الأخرى دون تغيير. المؤشر المأخوذ من طلب مختلف يُعيد 400 invalid_. يعدّ total الصفوف المتطابقة في كل الصفحات. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة.
السعر
الطلب الذي يُعيد صفًا واحدًا على الأقل يُحتسب استدعاءً واحدًا، بسعر $2 لكل 1,000 استدعاء. وكل صفحة من إجابة طويلة تُحتسب استدعاءً واحدًا، أيًّا كانت قيمة limit. الإجابة بلا صفوف مجانية، وكذلك كل خطأ.
الأخطاء
تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء 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 | 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 | تعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل. |
هل كانت هذه الصفحة مفيدة؟