加拿大统计局数据 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。此请求读取 July 至 September 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 October 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，在 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 响应头。