通过表格 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。响应还包含署名信息和许可 URL。保留或展示数据时，请同时保留这些信息。
   读取向量定义

   复制

   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，因此请在保留结果时一并保留该标签。

加拿大统计局响应包含加拿大开放政府许可的署名信息和许可 URL。该序列不提供修订历史或历史版本。历史访问范围取决于套餐：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。观测记录状态与响应新鲜度描述的是不同属性。