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

البيانات التي يمكنك قراءتها

تحتوي API لبيانات هيئة الإحصاء الكندية على مسارات لتعريف السلسلة والمشاهدات التاريخية وأحدث مشاهدة. للحصول على بيانات CPI أو GDP أو العمل أو التجارة، حدد المتجه الخاص بالمقياس الذي تحتاج إليه، ثم استخدم معرّفه في كل طلب.

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

ابحث عن متجه جدول

ابحث في الفهرس باستخدام source=statcan واستعلام بطول 2-100 حرف. تحدد كل نتيجة جدولًا، مع رقم الجدول في العنوان، مثل 10-10-0106-01. تتضمن النتيجة قالب المعرّف statcan:v{vector}.

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

ابحث عن رقم المتجه في صفحة الجدول على statcan.gc.ca، ثم استبدل {vector} بذلك الرقم. لا توفر Narwhal بعد مسارًا يسرد متجهات الجدول. البحث في الفهرس متاح على جميع الخطط ولا يرسل طلبات إلى هيئة الإحصاء الكندية.

اقرأ السلسلة

مرر معرّف السلسلة الكامل في معامل الاستعلام id. يقرأ هذا الطلب الفترة من يوليو إلى سبتمبر 2026، بما يشمل فترتي البداية والنهاية. تستخدم النطاقات الشهرية YYYY-MM؛ وتستخدم النطاقات الربع سنوية YYYY-Qn، والسنوية YYYY.

import os
import requests

response = requests.get(
    "https://api.narwhalapi.com/v1/economics/catalogue/series/observations",
    headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
    params={
        "id": "statcan:v41690973",
        "start": "2026-07",
        "end": "2026-09",
        "limit": 3,
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

تتضمن المشاهدات المحفوظة في 27 أكتوبر 2026 القيم وتواريخ الإصدار التالية:

{
  "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
}

اقرأ عدة سلاسل دفعة واحدة

استخدم /v1/economics/catalogue/latest مع ما يصل إلى 50 معرّفًا مختلفًا في معامل الاستعلام ids، مفصولة بفواصل. تحتوي الاستجابة على أحدث المشاهدات وقائمة missing. يستخدم REST وأداة MCP المسماة economics_read_catalogue_latest_batch عملية الدُفعة نفسها.

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

البيانات غير المقدمة

تُرجع المتجهات اليومية والأسبوعية ومتعددة السنوات والخاصة بالسنة المالية والربع المالي 404 not_found. وجود جدول في فهرس البحث لا يغير قيود التواتر هذه.

تحتفظ المشاهدات المدعومة بمؤشرات الحالة مثل provisional أو estimated عند ورودها. تحقق من هذه المؤشرات مع الفترة وتسمية الوحدة قبل استخدام قيمة في عملية حسابية. لا تملأ API الفجوات ولا تعيد بناء الإصدارات السابقة من السلسلة.

الحدود حسب الخطة

تحتفظ كل خطة بما لا يقل عن أحدث 5 مشاهدات سنوية وأحدث 4 مشاهدات ربع سنوية، حتى إن كانت خارج نطاقها الزمني للبيانات التاريخية. تبقى السلاسل المخزنة مؤقتًا قابلة للقراءة بعد استنفاد الحصة اليومية لعمليات الجلب.

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

الرخصة

تخضع بيانات هيئة الإحصاء الكندية لرخصة الحكومة المفتوحة - كندا. تتضمن كل استجابة لسلسلة attribution وlicence_url؛ احتفظ بمعلومات الرخصة هذه مع البيانات التي تستخدمها.

يحتوي فهرس البحث على 1,914 جدولًا حاليًا من هيئة الإحصاء الكندية. تحدد نتائج البحث الجداول، بينما تحدد معرّفات المتجهات السلاسل الفردية التي تُقرأ عبر API.

ما معرّف المتجه لدى هيئة الإحصاء الكندية؟

يحدد رقم المتجه سلسلة فردية من هيئة الإحصاء الكندية. تكتبه Narwhal بالصيغة statcan:v<vector>، مثل statcan:v41690973. يحدد رقم الجدول الجدول الذي تجد فيه المتجه؛ ولا يمكن استخدامه بدلًا من المتجه في طلب سلسلة.

ما وتيرة تحديث بيانات هيئة الإحصاء الكندية هنا؟

تدوم صلاحية التخزين المؤقت 6 ساعات للسلاسل الشهرية، و12 ساعة للسلاسل الربع سنوية، و24 ساعة للسلاسل السنوية. عند حلول موعد الإصدار التالي، تُجرى التحديثات كل 15 دقيقة.

إذا تعذر الاتصال بهيئة الإحصاء الكندية، يمكن إرجاع نسخة محفوظة مع stale: true. وفي حال عدم وجود نسخة مخزنة مؤقتًا، يُرجع الطلب 503 upstream_busy وترويسة Retry-After.