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

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

اسأل عن أي دول مُبلِّغة وشركاء وفصول HS في استدعاء واحد، مثل أكبر المصدّرين لمنتج ما أو دولة مقابل أخرى.

نظرة عامة

GET /v1/trade/flows

يُعيد GET /v1/trade/flows الصادرات والواردات لأي دول مُبلِّغة وشركاء وفصول HS تسمّيها، في استدعاء واحد. يقبل كل من reporter وpartner وhs قائمة مفصولة بفواصل حتى 10 عناصر. الصف الواحد هو دولة مُبلِّغة وشهر واتجاه وشريك وفصل.

استخدمه للأسئلة التي تعبر الدول أو المنتجات: من يصدّر فصلًا ما، وكيف تتاجر دولة مع أخرى، أو دولتان جنبًا إلى جنب. سمِّ واحدًا على الأقل من reporter وpartner وhs. عند حذف reporter يعني ذلك كل دولة تحتفظ بها Narwhal مباشرة، من مكتبها الخاص أو من UN Comtrade.

يسمّي كل صف basis وsource وcurrency الخاصة به، لأن الدول المُبلِّغة قد تُجيب من مصادر مختلفة. لا تُجمع أبدًا صفوف من مصادر مختلفة. النافذة 12 شهرًا على الأكثر، ومن دون start وend تُجيب كل دولة مُبلِّغة بأحدث شهر لديها. من دون hs تكون الصفوف إجماليات الشركاء، ومع hs تكون صفوف فصول. أداة MCP هي trade_get_flows وتأخذ المعلمات نفسها.

طلب

صادرات الفصل 85 (الآلات الكهربائية) للمملكة المتحدة وألمانيا في يونيو 2026، الصفحة الأولى من خمس:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/flows?reporter=GBR,DEU&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"
صادرات الفصل 85، المملكة المتحدة وألمانيا
{
  "scope": "goods",
  "bases": [
    "own"
  ],
  "reporters": [
    "DEU"
  ],
  "latest_period": "2026-06",
  "note": null,
  "fx": null,
  "calculated": [],
  "total": 396,
  "rows": [
    {
      "reporter": "DEU",
      "basis": "own",
      "source": "Eurostat Comext",
      "currency": "EUR",
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "partner": "ABW",
      "partner_label": "Aruba",
      "partner_kind": "country",
      "unallocated_reason": null,
      "product_code": "85",
      "value": "108666",
      "net_weight_kg": "731"
    },
    {
      "reporter": "DEU",
      "basis": "own",
      "source": "Eurostat Comext",
      "currency": "EUR",
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "partner": "AFG",
      "partner_label": "Afghanistan",
      "partner_kind": "country",
      "unallocated_reason": null,
      "product_code": "85",
      "value": "153236",
      "net_weight_kg": "2893"
    }
  ],
  "next_cursor": "eyJiIjoiZW5kPTIwMjYtMDZ8Zmxvdz1leHBvcnR8aHM9ODV8aW5jbHVkZV9ncm91cHM9RmFsc2V8cmVwb3J0ZXI9R0JSLERFVXxzdGFydD0yMDI2LTA2IiwibyI6NX0"
}

تعرض الصفحة أول صفين من الصفوف الخمسة. total هو 396، لذا تتبعها صفحات أخرى. تحتوي الصفحة 1 على صفوف ألمانيا فقط، ويسرد reporters الدول المُبلِّغة في الصفحة، فيعرض DEU وحده مع أن دولتين طُلبتا.

المعلمات

معلمةالموضعالنوعمطلوبالافتراضيالقيم المسموح بها ومعناها
reporterاستعلامسلسلة نصيةلاكل دولة محفوظة مباشرةالدول المُبلِّغة، برموز ISO 3166-1 alpha-3 بأحرف كبيرة، كقائمة مفصولة بفواصل حتى 10 عناصر، مثل GBR,DEU. الرمز الذي لا يعود لدولة يُعيد 400 ويسمّي الرمز. الدولة خارج قائمة التغطية تُعيد 404 country_not_covered. الدولة المُبلِّغة التي لا يحتفظ بها أي مصدر خاص بها تُجاب من تقارير الدول الأخرى ويجب تسميتها.
partnerاستعلامسلسلة نصيةلاكل الشركاءالشركاء، برموز ISO 3166-1 alpha-3 بأحرف كبيرة، كقائمة مفصولة بفواصل حتى 10 عناصر.
hsاستعلامسلسلة نصيةلالا شيءفصول HS، من رقمين (2)، كقائمة مفصولة بفواصل حتى 10 عناصر، مثل 85,87. تكون الصفوف حينئذ صفوف فصول. عند الحذف تكون الصفوف إجماليات الشركاء. لا يحتفظ الاستعلام المفتوح إلا بالفصول.
flowاستعلامسلسلة نصيةلاالاتجاهانexport أو import.
startاستعلامسلسلة نصية، YYYY-MMلاأحدث شهر لكل دولة مُبلِّغةأول شهر، شاملًا. من start إلى end 12 شهرًا على الأكثر.
endاستعلامسلسلة نصية، YYYY-MMلاأحدث شهر لكل دولة مُبلِّغةآخر شهر، شاملًا. مع واحد فقط من start وend يكون ذلك الشهر وحده.
basisاستعلامسلسلة نصيةلاأفضل مصدر تحتفظ به كل دولة مُبلِّغةown أو third_party أو partner_reported. هذا المصدر وحده يُجيب. المصدر الذي لا صفوف له للسؤال يُعيد 404 basis_not_available.
currencyاستعلامسلسلة نصيةلاعملة كل دولة مُبلِّغة نفسها، مذكورة في كل صفUSD. يحوّل كل صف بمتوسط السعر اليومي لشهره.
include_groupsاستعلاممنطقيلاfalsetrue يُعيد أيضًا صفوف المجموعات التي ينشرها الناشر، مثل الاتحاد الأوروبي أو ASEAN. لا يدخل صف المجموعة أبدًا في مجموع أو ترتيب أو حصة.
limitاستعلامعدد صحيحلا500من 1 إلى 1000. أكبر عدد من الصفوف في صفحة واحدة.
cursorاستعلامسلسلة نصيةلالا شيءقيمة next_cursor من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير.

الاستجابة

تحتوي الإجابة على هذه الحقول.

حقلالمعنى
scopegoods.
basesالمصادر التي تأتي منها صفوف هذه الإجابة، كل منها own أو third_party أو partner_reported.
reportersالدول المُبلِّغة التي لها صفوف في هذه الصفحة، مرتبة. قد تسرد صفحة لاحقة المزيد.
latest_periodأحدث شهر بين الصفوف المحفوظة مباشرة. null عند عدم وجود أي منها.
noteاقرأ هذا قبل استخدام الأرقام. يُضبط عندما يكون صف ما من تقارير الشركاء، وnull خلاف ذلك.
fxمع currency=USD: السعر المستخدم لكل شهر، مع period وfrom_currency وto_currency وrate وdays. null خلاف ذلك.
calculatedأسماء الحقول التي حسبتها Narwhal.
totalعدد الصفوف المتطابقة في كل الصفحات.
next_cursorمؤشر الصفحة التالية. null في الصفحة الأخيرة.

كل عنصر في rows هو دولة مُبلِّغة وشهر واتجاه وشريك وفصل.

حقلالمعنى
reporterرمز ISO 3166-1 alpha-3 للدولة المُبلِّغة.
basisمصدر هذا الصف: own أو third_party أو partner_reported.
sourceالجهة الناشرة لهذا الصف.
currencyرمز ISO 4217 لقيمة هذا الصف.
flowexport أو import.
periodالشهر، YYYY-MM.
period_typemonth.
period_start, period_endأول يوم وآخر يوم يغطيهما الصف، YYYY-MM-DD.
partner, partner_label, partner_kind, unallocated_reasonكما في مسار الشركاء.
product_codeالفصل عند إرسال hs. null لإجمالي شريك.
valueوحدات كاملة من currency، كسلسلة عشرية.
net_weight_kgالوزن الصافي بالكيلوغرام حيث يقدّمه الناشر. null خلاف ذلك.

أمثلة إضافية

تُتخطى الدول المُبلِّغة التي لا تقدّم إلا إجماليات الشركاء

واردات الولايات المتحدة من الصين في الفصل 85، مع تسمية كندا والمكسيك أيضًا. مكاتبهما الخاصة لا تقدّم إلا إجماليات الشركاء، لذلك تُجيب الولايات المتحدة وحدها:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/flows?reporter=USA,CAN,MEX&partner=CHN&hs=85&start=2026-06&end=2026-06&flow=import&limit=5"
واردات الفصل 85 من الصين
{
  "scope": "goods",
  "bases": [
    "own"
  ],
  "reporters": [
    "USA"
  ],
  "latest_period": "2026-06",
  "note": null,
  "fx": null,
  "calculated": [],
  "total": 1,
  "rows": [
    {
      "reporter": "USA",
      "basis": "own",
      "source": "US Census Bureau",
      "currency": "USD",
      "flow": "import",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null,
      "product_code": "85",
      "value": "5834371932",
      "net_weight_kg": null
    }
  ],
  "next_cursor": null
}

الدول المُبلِّغة ذات إجماليات الشركاء فقط

عندما تقدّم كل دولة مُبلِّغة مسمّاة إجماليات الشركاء فقط ويُرسل hs، يُعيد الاستدعاء 404 وهو مجاني:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/flows?reporter=CAN&hs=85&start=2026-06&end=2026-06&limit=4"
كندا، الفصل 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. See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "3dd0d00d-a61f-488c-ab1b-e121c37e4980"
}

المصادر

تُجيب كل دولة مُبلِّغة من أفضل مصدر محفوظ لها: مكتبها الخاص، ثم إيداعها لدى UN Comtrade (إجماليات الشركاء فقط)، والدولة المُبلِّغة التي لا يحتفظ بها أي منهما تُجاب من تقارير الدول الأخرى، ويحمل ذلك الوسم partner_reported. بحسب الفصل لا تحتفظ UN Comtrade بشيء. يفرض basis مصدرًا واحدًا على كل الدول المُبلِّغة. الدولة المُبلِّغة التي لا يقدّم مكتبها الخاص إلا إجماليات الشركاء لا صفوف فصول لها: تُتخطى عندما تُجيب دول مُبلِّغة أخرى، ويُعيد الاستدعاء 404 basis_not_available عندما لا تستطيع أي منها الإجابة.

العملة

كل صف بعملة دولته المُبلِّغة نفسها، المذكورة في currency الخاص بالصف. يحوّل currency=USD كل صف بمتوسط السعر اليومي لشهره ويسرد الأسعار في fx. الشهر بلا سعر يُعيد 404 rate_not_available، ومصدر الأسعار غير المتاح يُعيد 503 upstream_unavailable.

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

يحدد 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لم تُسمَّ reporter ولا partner ولا hs (an open query with none is the whole store)، أو end قبل start، أو النافذة أكثر من 12 شهرًا، أو قائمة تحتوي على أكثر من 10 عناصر، أو دولة مُبلِّغة ليست دولة، أو معلمة خارج قيمها المسموح بها، أو أُرسل as_of أو version. وكذلك عندما تحتاج إجابة تقارير الشركاء إلى أكثر من 30 تركيبة من الدولة المُبلِّغة والشريك والفصل.
400invalid_cursorالمؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك.
400range_too_largeستحتوي الإجابة على أكثر من 200,000 صف، أو تغطي صفوف الفصول بلا شريك أكثر من 36 شهرًا لدولة مُبلِّغة. سمِّ عددًا أقل من الدول المُبلِّغة أو الشركاء أو الفصول، أو نافذة أقصر.
404country_not_coveredدولة مُبلِّغة مسمّاة ليست في قائمة التغطية (ATA is not in the trade coverage list.).
404basis_not_availableيسمّي basis مصدرًا لا صفوف له للسؤال، أو أن كل دولة مُبلِّغة مسمّاة لا تقدّم إلا إجماليات الشركاء وأُرسل hs.
404rate_not_availableطُلب currency=USD ولا يوجد سعر صرف لأحد الأشهر.
503upstream_unavailableمصدر أسعار الصرف لا يستطيع الإجابة. يؤثر ذلك في currency=USD وفي إجابات تقارير الشركاء التي تحتاج إلى تحويل. حاول مرة أخرى بعد قليل.
503trade_data_unavailableتعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل.

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

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