加拿大統計局資料 API

可讀取的資料

加拿大統計局資料 API 提供序列定義、歷史觀測值及最新觀測值的路由。若要取得 CPI、GDP、勞動或貿易資料，請先找出所需指標的向量，再於每次請求中使用其 ID。

回應保留來源的單位標籤與季節調整資訊。觀測值為十進位字串，若有發布日期則會一併提供。缺少資料的期間會省略。即時序列不提供修訂歷程或歷次發布版本。

尋找資料表的向量

以 source=statcan 及 2-100 個字元的查詢文字搜尋目錄。每筆結果代表一個資料表，標題包含資料表編號，例如 10-10-0106-01。結果的 ID 範本為 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 查詢參數中傳入完整的序列 ID。此請求讀取 2026 年 7 月至 9 月的資料，包含起始與結束期間。月份範圍使用 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())

2026 年 10 月 27 日擷取的觀測資料包含下列數值與發布日期：

{
  "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，在 ids 查詢參數中傳入最多 50 個不重複的 ID，以逗號分隔。回應包含最新觀測值與 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 個資料表。搜尋結果識別資料表，向量 ID 則識別透過 API 讀取的個別序列。

什麼是加拿大統計局向量 ID？

向量編號用來識別加拿大統計局的個別序列。Narwhal 將其寫為 statcan:v<vector>，例如 statcan:v41690973。資料表編號用來識別向量所在的資料表，不能在序列請求中取代向量。

這裡的加拿大統計局資料多久更新一次？

月序列快取 6 小時，季序列快取 12 小時，年度序列快取 24 小時。下一次發布時間到達後，每 15 分鐘更新一次。

若無法連線至加拿大統計局，可回傳保留的副本，並標示 stale: true。若沒有快取副本，請求會回傳 503 upstream_busy 與 Retry-After 標頭。