캐나다 통계청 데이터 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 쿼리 매개변수에 서로 다른 ID를 최대 50개까지 쉼표로 구분해 전달합니다. 응답에는 최신 관측값과 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 헤더를 반환합니다.