透過 ID 取得加拿大統計局資料表

使用 API

1. 設定你的 API 金鑰 將 Narwhal API 金鑰設為 NARWHAL_API_KEY，並安裝 Python requests 函式庫。每個 Python 範例都會從該環境變數讀取金鑰，並在 Authorization 標頭中傳送。請在設定該變數的同一個 shell 中執行範例。若需要金鑰，可以先建立帳號。
   準備 shell 環境

   複製

   export NARWHAL_API_KEY="YOUR_API_KEY"
   python -m pip install requests

2. 搜尋資料表 使用 q 和 source=statcan 搜尋。若有資料表編號，請直接使用；也可以依消費者物價等主題搜尋。印出標題、頻率、第一個期間及最後一個期間，以檢查結果。所有方案皆可使用目錄搜尋，且不會呼叫加拿大統計局。資料表搜尋結果的範本為 statcan:v{vector}；你仍需要取得序列向量編號。
   尋找加拿大統計局資料表

   複製

   import os
   import requests
   
   response = requests.get(
       "https://api.narwhalapi.com/v1/economics/catalogue",
       headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
       params={"q": "10-10-0106-01", "source": "statcan", "limit": 25},
       timeout=10,
   )
   response.raise_for_status()
   for table in response.json()["results"]:
       print(
           table["title"],
           table["frequency"],
           table.get("first_period"),
           table.get("last_period"),
           sep=" | ",
       )

3. 複製序列向量編號 從結果標題讀取資料表編號。例如，消費者物價搜尋包含一筆月資料結果，其標題含有 Statistics Canada table 10-10-0106-01。在 statcan.gc.ca 開啟所選資料表的頁面，並複製所需序列的向量編號。向量格式為 v 後接數字，例如 v41690973。發送 API 請求時，請加上 statcan: 前綴。資料表編號用來識別資料表；向量則用來識別要讀取的序列。
4. 檢查序列定義 在 id 查詢參數中傳送完整序列 ID。使用數值前，請先檢查回傳的標題、頻率及 unit_label。對於 statcan:v41690973，標題為 Canada;All-items，頻率為每月，單位標籤為 2002=100。回應也包含來源標示與授權網址。保留或顯示資料時，請一併保留這些詳細資訊。
   讀取向量定義

   複製

   import os
   import requests
   
   response = requests.get(
       "https://api.narwhalapi.com/v1/economics/catalogue/series",
       headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
       params={"id": "statcan:v41690973"},
       timeout=10,
   )
   response.raise_for_status()
   series = response.json()
   for field in ("id", "title", "frequency", "unit_label", "attribution", "licence_url"):
       print(f"{field}: {series[field]}")

5. 一次讀取多個最新數值 若要查詢多個向量，請將其完整 ID 以逗號分隔，作為單一 ids 參數傳送至最新資料路由。每批最多接受 50 個不重複的 ID，並一次計入用量，每個回傳序列計入一次呼叫。範例以 v41690973 開始，這是來自資料表 18-10-0004-01 的加拿大全項目消費者物價指數。將複製的其他向量編號加入清單，再檢查回傳的觀測資料與 missing 清單。
   批次取得向量最新數值

   複製

   import os
   import requests
   
   vectors = ["v41690973"]  # Add other vector numbers copied from table pages.
   ids = list(dict.fromkeys(f"statcan:{vector}" for vector in vectors))
   if not 1 <= len(ids) <= 50:
       raise ValueError("Supply between 1 and 50 distinct series ids")
   
   response = requests.get(
       "https://api.narwhalapi.com/v1/economics/catalogue/latest",
       headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
       params={"ids": ",".join(ids)},
       timeout=10,
   )
   response.raise_for_status()
   data = response.json()
   for observation in data["observations"]:
       print(observation["id"], observation["period"], observation["value"])
   print("Missing:", data["missing"])

6. 讀取歷史資料並計算月變動率 使用觀測資料路由查詢期間範圍。起始與結束期間皆包含在內，且必須使用相同的期間格式；月資料序列使用 YYYY-MM。此完整範例請求 2026 年 7 月至 9 月的資料，並計算 9 月相較於 8 月的變動率。數值以十進位字串回傳，因此計算使用 Decimal。印出的結果四捨五入至小數點後兩位。
   計算 CPI 月增率

   複製

   import os
   from decimal import Decimal
   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": 100,
       },
       timeout=10,
   )
   response.raise_for_status()
   series = response.json()
   values = {}
   for observation in series["observations"]:
       values[observation["period"]] = Decimal(observation["value"])
       print(
           observation["period"],
           observation["value"],
           observation.get("released_on", ""),
           observation.get("status", ""),
       )
   
   change = (values["2026-09"] / values["2026-08"] - Decimal("1")) * Decimal("100")
   print(f"September 2026 month-on-month change: {change:.2f}%")

透過 CPI 向量計算月變動率

擷取的 statcan:v41690973 回應包含以下加拿大全項目 CPI 觀測資料。每列都有觀測期間、十進位數值及發布日期。請將發布日期與數值所描述的月份分開保留。

9 月的月增率為 (170.0 / 169.8 - 1) * 100，約為 0.1178%。四捨五入至小數點後兩位，結果為 0.12%。此計算比較的是連續月份的指數水準。回傳的 seasonal_adjustment 為 not_stated，因此請在結果旁一併保留此標籤。

加拿大統計局回應包含「加拿大開放政府授權條款」的來源標示與授權網址。序列不提供修訂歷史或歷次發布版本。歷史資料存取依方案而定：Free 提供最近 12 個月，Basic 提供最近 5 年，Pro 提供完整歷史資料。分頁說明請參閱序列 API 參考文件，存取限制請參閱方案。

哪些加拿大統計局序列無法使用？

每日、每週、跨年度、會計年度及會計季度向量會回傳 404 not_found。Narwhal 支援加拿大統計局的每月、每季及每年向量。從資料表頁面複製向量編號前，請先檢查目錄結果中的頻率。

向量 ID 格式錯誤時，會回傳 400 invalid_series_id。其詳細說明會指出加拿大統計局序列 ID 的格式為 v<vector number>。請透過 id 參數傳入完整 ID，例如 statcan:v41690973。錯誤處理請參閱 API 錯誤。

如何讀取數值狀態？

請讀取每筆觀測資料中選填的 status 欄位。當數值具有 provisional 或 estimated 等狀態時，此欄位就會出現。請將其與期間及數值一併保留，讓計算結果保有這項背景資訊。

若有 released_on，請予以保留，並使用 fetched_at 作為擷取時間戳記。只有當來源無法連線，Narwhal 因而提供最後保留的副本時，回應才會包含 stale: true。觀測資料狀態與回應新鮮度描述的是不同屬性。