مرجع API للاستعلام المفتوح عن التجارة
اسأل عن أي دول مُبلِّغة وشركاء وفصول HS في استدعاء واحد، مثل أكبر المصدّرين لمنتج ما أو دولة مقابل أخرى.
نظرة عامة
GET /
يُعيد GET / الصادرات والواردات لأي دول مُبلِّغة وشركاء وفصول HS تسمّيها، في استدعاء واحد. يقبل كل من reporter وpartner وhs قائمة مفصولة بفواصل حتى 10 عناصر. الصف الواحد هو دولة مُبلِّغة وشهر واتجاه وشريك وفصل.
استخدمه للأسئلة التي تعبر الدول أو المنتجات: من يصدّر فصلًا ما، وكيف تتاجر دولة مع أخرى، أو دولتان جنبًا إلى جنب. سمِّ واحدًا على الأقل من reporter وpartner وhs. عند حذف reporter يعني ذلك كل دولة تحتفظ بها Narwhal مباشرة، من مكتبها الخاص أو من UN Comtrade.
يسمّي كل صف basis وsource وcurrency الخاصة به، لأن الدول المُبلِّغة قد تُجيب من مصادر مختلفة. لا تُجمع أبدًا صفوف من مصادر مختلفة. النافذة 12 شهرًا على الأكثر، ومن دون start وend تُجيب كل دولة مُبلِّغة بأحدث شهر لديها. من دون hs تكون الصفوف إجماليات الشركاء، ومع hs تكون صفوف فصول. أداة MCP هي trade_ وتأخذ المعلمات نفسها.
طلب
صادرات الفصل 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"{
"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_. الدولة المُبلِّغة التي لا يحتفظ بها أي مصدر خاص بها تُجاب من تقارير الدول الأخرى ويجب تسميتها. |
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_ أو partner_. هذا المصدر وحده يُجيب. المصدر الذي لا صفوف له للسؤال يُعيد 404 basis_. |
currency | استعلام | سلسلة نصية | لا | عملة كل دولة مُبلِّغة نفسها، مذكورة في كل صف | USD. يحوّل كل صف بمتوسط السعر اليومي لشهره. |
include_ | استعلام | منطقي | لا | false | true يُعيد أيضًا صفوف المجموعات التي ينشرها الناشر، مثل الاتحاد الأوروبي أو ASEAN. لا يدخل صف المجموعة أبدًا في مجموع أو ترتيب أو حصة. |
limit | استعلام | عدد صحيح | لا | 500 | من 1 إلى 1000. أكبر عدد من الصفوف في صفحة واحدة. |
cursor | استعلام | سلسلة نصية | لا | لا شيء | قيمة next_ من الصفحة السابقة، مع بقاء كل المعلمات الأخرى دون تغيير. |
الاستجابة
تحتوي الإجابة على هذه الحقول.
| حقل | المعنى |
|---|---|
scope | goods. |
bases | المصادر التي تأتي منها صفوف هذه الإجابة، كل منها own أو third_ أو partner_. |
reporters | الدول المُبلِّغة التي لها صفوف في هذه الصفحة، مرتبة. قد تسرد صفحة لاحقة المزيد. |
latest_ | أحدث شهر بين الصفوف المحفوظة مباشرة. null عند عدم وجود أي منها. |
note | اقرأ هذا قبل استخدام الأرقام. يُضبط عندما يكون صف ما من تقارير الشركاء، وnull خلاف ذلك. |
fx | مع currency=USD: السعر المستخدم لكل شهر، مع period وfrom_ وto_ وrate وdays. null خلاف ذلك. |
calculated | أسماء الحقول التي حسبتها Narwhal. |
total | عدد الصفوف المتطابقة في كل الصفحات. |
next_ | مؤشر الصفحة التالية. null في الصفحة الأخيرة. |
كل عنصر في rows هو دولة مُبلِّغة وشهر واتجاه وشريك وفصل.
| حقل | المعنى |
|---|---|
reporter | رمز ISO 3166-1 alpha-3 للدولة المُبلِّغة. |
basis | مصدر هذا الصف: own أو third_ أو partner_. |
source | الجهة الناشرة لهذا الصف. |
currency | رمز ISO 4217 لقيمة هذا الصف. |
flow | export أو import. |
period | الشهر، YYYY-MM. |
period_ | month. |
period_ | أول يوم وآخر يوم يغطيهما الصف، YYYY-MM-DD. |
partner, partner_ | كما في مسار الشركاء. |
product_ | الفصل عند إرسال hs. null لإجمالي شريك. |
value | وحدات كاملة من currency، كسلسلة عشرية. |
net_ | الوزن الصافي بالكيلوغرام حيث يقدّمه الناشر. 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"{
"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"{
"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_. بحسب الفصل لا تحتفظ UN Comtrade بشيء. يفرض basis مصدرًا واحدًا على كل الدول المُبلِّغة. الدولة المُبلِّغة التي لا يقدّم مكتبها الخاص إلا إجماليات الشركاء لا صفوف فصول لها: تُتخطى عندما تُجيب دول مُبلِّغة أخرى، ويُعيد الاستدعاء 404 basis_ عندما لا تستطيع أي منها الإجابة.
العملة
كل صف بعملة دولته المُبلِّغة نفسها، المذكورة في currency الخاص بالصف. يحوّل currency=USD كل صف بمتوسط السعر اليومي لشهره ويسرد الأسعار في fx. الشهر بلا سعر يُعيد 404 rate_، ومصدر الأسعار غير المتاح يُعيد 503 upstream_.
التصفح بالصفحات
يحدد limit أكبر عدد من الصفوف في صفحة واحدة، من 1 إلى 1000، وقيمته الافتراضية 500. عندما تتطابق صفوف أكثر، يحمل next_ مؤشر الصفحة التالية: أرسله كـcursor مع بقاء كل المعلمات الأخرى دون تغيير. المؤشر المأخوذ من طلب مختلف يُعيد 400 invalid_. يعدّ total الصفوف المتطابقة في كل الصفحات. تُعيد أداة MCP ما لا يزيد على 200 صف في نتيجة واحدة.
السعر
الطلب الذي يُعيد صفًا واحدًا على الأقل يُحتسب استدعاءً واحدًا، بسعر $2 لكل 1,000 استدعاء. وكل صفحة من إجابة طويلة تُحتسب استدعاءً واحدًا، أيًّا كانت قيمة limit. الإجابة بلا صفوف مجانية، وكذلك كل خطأ.
الأخطاء
تستخدم هذه الأخطاء بنية تفاصيل الخطأ المشتركة مع request_. المفتاح المفقود أو غير الصالح (401)، والرصيد الأقل من سعر الاستدعاء (402)، وكثرة الطلبات في الدقيقة (429) هي أخطاء الحساب التي تشترك فيها كل المسارات: راجع أخطاء API والرصيد.
| الحالة | الرمز | متى يحدث |
|---|---|---|
400 | invalid_query | لم تُسمَّ reporter ولا partner ولا hs (an open query with none is the whole store)، أو end قبل start، أو النافذة أكثر من 12 شهرًا، أو قائمة تحتوي على أكثر من 10 عناصر، أو دولة مُبلِّغة ليست دولة، أو معلمة خارج قيمها المسموح بها، أو أُرسل as_ أو version. وكذلك عندما تحتاج إجابة تقارير الشركاء إلى أكثر من 30 تركيبة من الدولة المُبلِّغة والشريك والفصل. |
400 | invalid_cursor | المؤشر ليس من المؤشرات التي أعادها هذا الطلب، أو تغيّرت معلمة أخرى منذ ذلك. |
400 | range_too_large | ستحتوي الإجابة على أكثر من 200,000 صف، أو تغطي صفوف الفصول بلا شريك أكثر من 36 شهرًا لدولة مُبلِّغة. سمِّ عددًا أقل من الدول المُبلِّغة أو الشركاء أو الفصول، أو نافذة أقصر. |
404 | country_not_covered | دولة مُبلِّغة مسمّاة ليست في قائمة التغطية (ATA is not in the trade coverage list.). |
404 | basis_not_available | يسمّي basis مصدرًا لا صفوف له للسؤال، أو أن كل دولة مُبلِّغة مسمّاة لا تقدّم إلا إجماليات الشركاء وأُرسل hs. |
404 | rate_not_available | طُلب currency=USD ولا يوجد سعر صرف لأحد الأشهر. |
503 | upstream_unavailable | مصدر أسعار الصرف لا يستطيع الإجابة. يؤثر ذلك في currency=USD وفي إجابات تقارير الشركاء التي تحتاج إلى تحويل. حاول مرة أخرى بعد قليل. |
503 | trade_data_unavailable | تعذّرت قراءة ملفات المنتجات الآن. حاول مرة أخرى بعد قليل. |
هل كانت هذه الصفحة مفيدة؟