API لبيانات البنك الدولي

اقرأ المؤشرات السنوية حسب البلد

اقرأ مؤشر WDI لبلد باستخدام wdi:<indicator>/<iso3>، مع مراعاة قيود الرخصة أدناه. يستخدم الجزآن أحرفًا صغيرة. جزء البلد هو رمز ISO 3166-1 alpha-3، مثل idn لإندونيسيا.

سلاسل WDI سنوية. تحافظ الاستجابات على تسمية وحدة المؤشر، وتكون قيم المشاهدات سلاسل نصية عشرية. تُحذف السنوات المفقودة ولا تُملأ مطلقًا. لا تتضمن السلسلة سجلًا للمراجعات أو نسخًا مؤرخة من البيانات.

ابحث عن مؤشر

ابحث في الفهرس باستخدام q واقصر النتائج على source=wdi. البحث متاح على جميع الخطط ولا يرسل أي طلب إلى المصدر. تقبل الاستعلامات من 2 إلى 100 حرف؛ ويقبل limit من 1 إلى 100 نتيجة، وقيمته الافتراضية 25.

curl "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "wdi:bg.gsr.nfsv.gd.zs/{country}",
      "source": "wdi",
      "title": "Trade in services (% of GDP)",
      "frequency": "annual",
      "unit_label": "Trade in services (% of GDP)"
    },
    {
      "id_template": "wdi:bm.klt.dinv.wd.gd.zs/{country}",
      "source": "wdi",
      "title": "Foreign direct investment, net outflows (% of GDP)",
      "frequency": "annual",
      "unit_label": "Foreign direct investment, net outflows (% of GDP)"
    }
  ],
  "next_cursor": "eyJhIjoid2RpOmJtLmtsdC5kaW52LndkLmdkLnpzIiwicSI6IjBhOTNhNWZiMmE1NzkzY2EifQ"
}

استبدل {country} في id_template الخاص بالنتيجة برمز البلد الذي تريده. أداة MCP المقابلة هي economics_search_catalogue.

اقرأ السلسلة

مرر المعرّف الكامل في معامل الاستعلام id، بما في ذلك الشرطة المائلة. اقرأ التعريف أولًا للتحقق من العنوان والتواتر وتسمية الوحدة. بالنسبة إلى الناتج المحلي الإجمالي لإندونيسيا، تسمية الوحدة لدى المصدر هي GDP (current US$).

curl "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "title": "GDP (current US$), Indonesia",
  "country": "IDN",
  "frequency": "annual",
  "unit": "extended",
  "unit_label": "GDP (current US$)",
  "seasonal_adjustment": "not_stated",
  "first_period": "1967",
  "last_period": "2025"
}

اقرأ المشاهدات بشكل منفصل. يستخدم الحدّان السنويان start وend الصيغة YYYY ويشملان سنتي البداية والنهاية. تقبل صفحات المشاهدات ما يصل إلى 1,000 سجل. في MCP، استخدم economics_read_catalogue_series للتعريف وeconomics_read_catalogue_observations للقيم.

curl "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "observations": [
    {"period": "1967", "value": "5667756627.92093"},
    {"period": "1968", "value": "7076465299.81141"},
    {"period": "1969", "value": "8337423312.88344"}
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

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

أرسل من 1 إلى 50 معرّف سلسلة مختلفًا في المعامل ids، مفصولة بفواصل، لقراءة أحدث مشاهداتها. أبقِ جزء المؤشر ثابتًا وغيّر رمز البلد لطلب المؤشر نفسه لبلدان متعددة.

curl "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,wdi:ny.gdp.mktp.cd/jpn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

تُحتسب كل سلسلة مُرجعة باستدعاء واحد، وتُحتسب الدُفعة في خطوة واحدة. تحقق من period لكل مشاهدة عند مقارنة القيم. أداة MCP هي economics_read_catalogue_latest_batch.

تحقق من الحدود حسب الخطة

تُطبَّق حصص جلب البيانات غير المخزنة مؤقتًا لكل حساب في اليوم بتوقيت UTC. لا يلزم الجلب إلا عند غياب السلسلة عن ذاكرة التخزين المؤقت؛ وتبقى السلاسل المخزنة مؤقتًا قابلة للقراءة بعد استنفاد الحصة اليومية.

يشمل الوصول السنوي النطاق الزمني للخطة أو أحدث 5 مشاهدات، أيهما يتضمن عددًا أكبر. يُرجع النطاق الذي يسبق بكامله البيانات التاريخية المسموح بها 403 plan_upgrade_required.

عندما يحتاج طلب إلى جلب بيانات بعد استنفاد الحصة، يُرجع 429 fetch_limit_reached مع Retry-After حتى 00:00 UTC. يتلقى الحساب الذي بلغ حده ولديه نسخة محفوظة تلك النسخة دون احتساب استخدام.

احتفظ بالرخصة ونسبة البيانات إلى مصدرها

يفهرس الفهرس 1,489 مؤشرًا من مؤشرات WDI التابعة للبنك الدولي بموجب CC BY 4.0. تُرفض تسعة مؤشرات ذات رخص أخرى عند طلبها بالمعرّف ولا تُقدَّم.

تتضمن كل استجابة لسلسلة attribution وlicence_url. احتفظ بنسبة البيانات إلى البنك الدولي ورخصة CC BY 4.0 مع البيانات التي تستخدمها. تتضمن الاستجابة أيضًا fetched_at، لتتمكن من تسجيل وقت جلب Narwhal للسلسلة إلى جانب فترات مشاهداتها.

كيف أحصل على مؤشر من البنك الدولي باستخدام رمز البلد؟

ابحث عن المؤشر، وخذ id_template الخاص به، واستبدل {country} برمز ISO 3166-1 alpha-3 بأحرف صغيرة. على سبيل المثال، سلسلة الناتج المحلي الإجمالي لإندونيسيا هي wdi:ny.gdp.mktp.cd/idn.

مرر ذلك المعرّف الكامل في المعامل id عند قراءة التعريف أو المشاهدات. أبقِ رمز البلد مرتبطًا بالمؤشر عند تخزين السلاسل أو مقارنتها.

ما مدى حداثة بيانات البنك الدولي؟

مشاهدات WDI سنوية، وتخزن Narwhal السلاسل مؤقتًا لمدة تتراوح من 24 ساعة إلى 7 أيام. عند عدم وجود السلسلة في ذاكرة التخزين المؤقت، تجلبها Narwhal من المصدر ضمن الحصة اليومية لخطتك.

تحقق من period للمشاهدة بشكل منفصل عن fetched_at: يحدد الأول سنة القياس، بينما يسجل الثاني وقت الجلب. إذا تعذر الاتصال بالمصدر، يمكن إرجاع نسخة محفوظة مع stale: true.