مرجع API السلاسل حسب المعرّف

ابحث في فهرسي البنك الدولي وهيئة الإحصاء الكندية واقرأ السلاسل حسب المعرّف، مع حدود الخطط والتخزين المؤقت ومعالجة الأخطاء.

تتيح أربع عمليات الوصول إلى سلاسل البنك الدولي وهيئة الإحصاء الكندية حسب المعرّف. ابحث في الفهرس، أو اقرأ تعريف سلسلة أو مشاهداتها، أو احصل على أحدث قيمة لما يصل إلى 50 سلسلة دفعة واحدة.

يشترك REST وMCP في المخططات والمفتاح والحصة. لا تتوفر سجلات مراجعات لسلاسل البنك الدولي وهيئة الإحصاء الكندية المباشرة التي تُقرأ حسب المعرّف. يمكن لمفاتيح Pro قراءة النسخ التاريخية على مسارات البيانات التاريخية للبلدان ومسارات السلاسل حسب المعرّف التي تدعمها، كما هو موضح في قسم سجل السلسلة حسب المعرّف في مرجع API البيانات الاقتصادية.

العمليات

عملية	مسار REST	أداة MCP	النتيجة
البحث في الفهرس	`GET /v1/economics/catalogue`	`economics_search_catalogue`	السلاسل والجداول المطابقة للاستعلام.
قراءة سلسلة	`GET /v1/economics/catalogue/series`	`economics_read_catalogue_series`	تعريف سلسلة واحدة.
قراءة المشاهدات	`GET /v1/economics/catalogue/series/observations`	`economics_read_catalogue_observations`	قيم سلسلة واحدة، بدءًا من الأقدم.
أحدث القيم	`GET /v1/economics/catalogue/latest`	`economics_read_catalogue_latest_batch`	أحدث قيمة لكل سلسلة ضمن مجموعة من 1 إلى 50 سلسلة.

قد يحتوي مفتاح المصدر على شرطة مائلة، لذا مرّر معرّف السلسلة في معامل الاستعلام id.

يتطلب كل طلب مفتاح Bearer. المصادقة

معرّفات السلاسل

تستخدم معرّفات السلاسل التنسيق <source>:<key> بأحرف صغيرة.

المصدر	التنسيق	مثال	الدوريات
البنك الدولي، مؤشرات التنمية العالمية	`wdi:<indicator>/<iso3>`	`wdi:ny.gdp.mktp.cd/idn`	سنوي
هيئة الإحصاء الكندية	`statcan:v<vector>`	`statcan:v41690973`	شهرية، ربع سنوية، سنوية

تتضمن نتائج البحث في البنك الدولي حقل id_template، مثل wdi:ny.gdp.mktp.cd/{country}. استبدل {country} برمز بلد وفق ISO 3166-1 alpha-3 بأحرف صغيرة. لا يشمل الفهرس إلا المؤشرات المنشورة بموجب CC BY 4.0؛ وتُرجع المؤشرات الأخرى 404 not_found.

تحدّد نتائج البحث في هيئة الإحصاء الكندية الجداول. تتضمن كل نتيجة حقل id_template بالقيمة statcan:v{vector} وعنوانًا يحتوي على رقم الجدول، مثل الجدول 10-10-0106-01. ابحث عن رقم متجه السلسلة في صفحة ذلك الجدول على موقع هيئة الإحصاء الكندية وأدرجه في القالب. لا يوجد حاليًا مسار يسرد متجهات جدول.

تُرجع متجهات هيئة الإحصاء الكندية ذات الدوريات اليومية أو الأسبوعية أو الممتدة لعدة سنوات أو المرتبطة بالسنة المالية أو ربع السنة المالية 404 not_found.

البحث في الفهرس

يستخدم البحث فهرس Narwhal دون استدعاء المصدر. وهو متاح في جميع الخطط ويُحتسب استدعاءً واحدًا.

q: نص البحث، من 2 إلى 100 حرف.
source: wdi أو statcan.
country: رمز ISO alpha-3 بأحرف كبيرة.
frequency: daily أو monthly أو quarterly أو annual.
limit: من 1 إلى 100؛ القيمة الافتراضية 25.
cursor: قيمة next_cursor من الصفحة السابقة.

تتضمن كل نتيجة source وtitle وواحدًا فقط من id أو id_template. وتتضمن أيضًا frequency وunit_label وcountry وfirst_period وlast_period عند توفرها. تكون قيمة next_cursor في الصفحة الأخيرة null.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  --header "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"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=consumer%20price&source=statcan&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Consumer Price Index (CPI) statistics, alternative measures, unadjusted and seasonally adjusted, Bank of Canada (Statistics Canada table 10-10-0106-01)",
      "frequency": "monthly",
      "country": "CAN",
      "first_period": "1979-11",
      "last_period": "2026-09"
    },
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Inter-city indexes of price differentials of consumer goods and services, annual (Statistics Canada table 18-10-0003-01)",
      "frequency": "annual",
      "country": "CAN",
      "first_period": "2000",
      "last_period": "2019"
    }
  ],
  "next_cursor": "eyJhIjoic3RhdGNhbjp0MTgxMDAwMDMiLCJxIjoiNGQxYjFkOWQwN2FlNTBhMiJ9"
}

قراءة سلسلة

يُرجع تعريف سلسلة واحدة، بما يشمل فترتيها الأولى والأخيرة. لا تُضمَّن المشاهدات.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "first_period": "1967",
  "last_period": "2025"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "first_period": "1914-01",
  "last_period": "2026-09"
}

قراءة المشاهدات

يُرجع قيم سلسلة واحدة مرتبة من الأقدم إلى الأحدث، مع تعريفها.

id: معرّف السلسلة.
start وend: حدّان مشمولان بتنسيق فترة السلسلة، YYYY أو YYYY-MM أو YYYY-Qn. يجب أن يستخدم الحدّان التنسيق نفسه.
limit: من 1 إلى 1000؛ القيمة الافتراضية 100.
cursor: قيمة next_cursor من الصفحة السابقة.

يطبّق Narwhal النطاق الزمني للبيانات التاريخية في خطتك بعد تطبيق start وend.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "observations": [
    {
      "period": "1967",
      "value": "5667756627.92093"
    },
    {
      "period": "1968",
      "value": "7076465299.81141"
    },
    {
      "period": "1969",
      "value": "8337423312.88344"
    }
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=statcan:v41690973&start=2026-07&limit=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "169.9",
      "released_on": "2026-08-17"
    },
    {
      "period": "2026-08",
      "value": "169.8",
      "released_on": "2026-09-14"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19"
    }
  ],
  "next_cursor": null
}

تُحذف السنوات أو الأشهر التي لم ينشر المصدر قيمًا لها، ولا تُملأ مطلقًا. تتضمن كل مشاهدة period وvalue، وهي سلسلة نصية تمثّل عددًا عشريًا؛ ويُضمَّن released_on وstatus عندما يوفّرهما المصدر.

أحدث القيم في طلب واحد

أرسل من 1 إلى 50 معرّفًا مختلفًا في قائمة ids مفصولة بفواصل. تُرجع الاستجابة أحدث مشاهدة لكل سلسلة وتعريفها. تحتوي قائمة missing على المعرّفات التي لا يتعرّف عليها المصدر أو التي لا تتوفر لها مشاهدة.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "observations": [
    {
      "period": "2025",
      "value": "1445642584163.81",
      "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",
      "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
      "licence_url": "https://creativecommons.org/licenses/by/4.0/",
      "fetched_at": "2026-10-27T03:37:35Z"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19",
      "id": "statcan:v41690973",
      "title": "Canada;All-items",
      "frequency": "monthly",
      "unit": "extended",
      "unit_label": "2002=100",
      "seasonal_adjustment": "not_stated",
      "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
      "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
      "fetched_at": "2026-10-27T12:30:59Z"
    }
  ],
  "missing": []
}

تُحتسب الدفعة في خطوة واحدة بمعدل استدعاء واحد لكل سلسلة مُرجعة.

حدود الخطط

تتوفر العمليات الأربع في جميع الخطط. تحدّد كل خطة حدًا يوميًا لعمليات الجلب من المصدر غير المخزّنة مؤقتًا ونطاقًا زمنيًا للبيانات التاريخية.

الحد	مجاني	Basic	Pro
عمليات الجلب غير المخزّنة مؤقتًا لكل يوم بتوقيت UTC	10	100	1,000
النطاق الزمني للبيانات التاريخية	آخر 12 شهرًا	آخر 5 سنوات	السجل التاريخي الكامل

تتضمن كل خطة أحدث 5 مشاهدات على الأقل للسلسلة السنوية وأحدث 4 مشاهدات للسلسلة ربع السنوية، حتى إن وقعت خارج نطاقها الزمني للبيانات التاريخية. يستخدم Narwhal ما يشمل مشاهدات أكثر: النطاق الزمني أو تلك المشاهدات الأحدث.

يُرجع النطاق الذي يقع بالكامل قبل النطاق الزمني لخطتك 403 plan_upgrade_required. بالنسبة إلى السلاسل السنوية وربع السنوية، يحمّل Narwhal السلسلة قبل هذا التحقق ليتمكن من تطبيق الحد الأدنى لعدد المشاهدات.

البيانات مباشرة دون تأخير.

الاستدعاءات والتخزين المؤقت والبيانات القديمة

يُحتسب كل طلب ناجح للبحث أو تعريف سلسلة أو مشاهداتها أو أحدث قيمة لسلسلة واحدة استدعاءً واحدًا. وتُحتسب الدفعات بمعدل استدعاء واحد لكل سلسلة مُرجعة.

لا تُحتسب الاستجابات التي تتضمن بيانات قديمة، ولا استجابات 400 و404 و503.

يخزّن Narwhal كل سلسلة مؤقتًا بعد قراءتها من المصدر. تُرجع السلسلة المخزّنة مؤقتًا استجابة دائمًا دون عملية جلب؛ ولا تُستخدم عملية جلب إلا لسلسلة غير مخزّنة مؤقتًا. تُخزَّن سلاسل البنك الدولي مؤقتًا لمدة تتراوح من 24 ساعة إلى 7 أيام. وتبلغ مدد التخزين المؤقت لهيئة الإحصاء الكندية 6 ساعات للسلاسل الشهرية و12 ساعة للسلاسل ربع السنوية و24 ساعة للسلاسل السنوية.

بعد أن يستنفد الحساب عمليات الجلب اليومية، يُرجع الطلب الذي يحتاج إلى عملية جلب إضافية 429 fetch_limit_reached. يبيّن ترويس Retry-After الوقت المتبقي حتى 00:00 UTC. إذا ظلت نسخة أقدم من السلسلة متاحة، يُرجعها Narwhal مع stale: true دون احتساب استدعاء.

إذا كان المصدر متوقفًا ولم توجد نسخة مخزّنة مؤقتًا، يُرجع Narwhal 503 upstream_busy مع Retry-After. لا تُمرَّر حدود معدل طلبات المصدر مطلقًا على شكل استجابات 429.

الحقول

تتضمن استجابات السلاسل هذه الحقول.

حقل	المعنى
`id`	معرّف السلسلة.
`title`	عنوان السلسلة كما يوفّره المصدر.
`country`	رمز ISO alpha-3، عندما يوفّره المصدر.
`frequency`	`daily` أو `monthly` أو `quarterly` أو `annual`.
`unit`	دائمًا `extended`.
`unit_label`	الوحدة بصياغة المصدر نفسه. تستخدم سلاسل البنك الدولي اسم المؤشر، مثل `GDP (current US$)`.
`scale, currency`	يُضمَّن فقط عندما يذكره المصدر. لا يطبّق Narwhal `scale` على القيم مطلقًا.
`seasonal_adjustment`	`seasonally_adjusted` أو `not_seasonally_adjusted` أو `not_applicable` أو `not_stated`.
`base_period`	أساس المؤشر، عندما يذكره المصدر.
`attribution, licence_url`	نسبة البيانات إلى المصدر المطلوبة ورابط ترخيص المصدر.
`fetched_at`	وقت قراءة Narwhal للمصدر.
`stale`	تكون القيمة `true` فقط عندما يتعذّر الوصول إلى المصدر ويُرجع Narwhal آخر نسخة احتفظ بها.
`first_period, last_period`	الفترتان الأولى والأخيرة، وتُضمَّنان في تعريف السلسلة.

الأخطاء

الحالة والرمز	المعنى
`400 invalid_series_id`	تنسيق المصدر في المعرّف غير صالح. تحدّد التفاصيل `<indicator>/<iso3 country>` للبنك الدولي أو `v<vector number>` لهيئة الإحصاء الكندية.
`400 invalid_query`	أحد المعاملات غير صالح. من الأمثلة وجود أكثر من 50 معرّفًا في دفعة، أو معرّفات مكررة، أو اختلاف تنسيق الفترة بين `start` و`end`.
`403 plan_upgrade_required`	ينتهي النطاق المطلوب قبل النطاق الزمني للبيانات التاريخية في خطتك.
`404 not_found`	لا يتعرّف المصدر أو الفهرس على السلسلة، أو أن دورية السلسلة غير مدعومة. يخزّن Narwhal هذه النتيجة مؤقتًا لمدة 24 ساعة.
`404 not_covered`	يشير المعرّف إلى مصدر غير مدعوم.
`429 fetch_limit_reached`	استنفد الحساب حصة الجلب لليوم بتوقيت UTC. يبيّن `Retry-After` الوقت المتبقي حتى 00:00 UTC.
`503 upstream_busy`	المصدر غير متاح ولا توجد نسخة مخزّنة مؤقتًا. انتظر المدة المحدّدة في `Retry-After` قبل المحاولة مجددًا.

تستخدم الأخطاء بنية المشكلة المشتركة وتتضمن request_id. الأخطاء والحصة

API لبيانات البنك الدولي · API لبيانات هيئة الإحصاء الكندية

نسبة البيانات إلى المصدر

تذكر كل استجابة اسم الجهة في attribution وتربط بترخيصها في licence_url. تستخدم مؤشرات البنك الدولي CC BY 4.0، وتستخدم بيانات هيئة الإحصاء الكندية ترخيص الحكومة المفتوحة - كندا. يوحّد Narwhal تنسيق القيم؛ حافظ على نسبتها إلى المصدر أينما تعرضها.

مرجع واجهة API للاقتصاد · MCP