ID로 캐나다 통계청 표 조회

API 사용 방법

1. API 키 설정 NARWHAL_API_KEY에 Narwhal API 키를 설정하고 Python requests 라이브러리를 설치하세요. 각 Python 예제는 이 환경 변수에서 키를 읽어 Authorization 헤더로 보냅니다. 변수를 설정한 셸에서 예제를 실행하세요. 키가 필요하면 계정을 생성할 수 있습니다.
   셸 준비

   복사

   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에서 선택한 표의 페이지를 열고 원하는 시계열의 벡터 번호를 복사하세요. 벡터는 v41690973처럼 v 뒤에 숫자가 오는 형태입니다. 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 매개변수로 최신값 경로에 보내세요. 일괄 요청은 서로 다른 ID를 최대 50개까지 허용하며, 반환된 시계열당 호출 1회가 한 번에 차감됩니다. 예제는 표 18-10-0004-01의 캐나다 전체 품목 소비자물가지수인 v41690973으로 시작합니다. 복사한 다른 벡터 번호를 목록에 추가한 다음, 반환된 관측값과 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월까지 요청하고 8월 대비 9월의 변동률을 계산합니다. 값이 소수 문자열로 반환되므로 계산에는 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이므로 결과와 함께 이 레이블을 보존하세요.

캐나다 통계청 응답에는 캐나다 공공정보 이용허락(Open Government Licence - Canada)에 따른 출처 표시와 라이선스 URL이 포함됩니다. 이 시계열에는 수정 이력이나 시점별 데이터 버전이 없습니다. 이력 이용 범위는 요금제에 따릅니다. Free는 최근 12개월, Basic은 최근 5년, Pro는 전체 이력을 제공합니다. 페이지 조회는 시계열 API 참조를, 이용 한도는 요금제를 확인하세요.

이용할 수 없는 캐나다 통계청 시계열은 무엇인가요?

일간, 주간, 다년, 회계연도, 회계분기 벡터는 404 not_found를 반환합니다. Narwhal은 캐나다 통계청의 월간, 분기별, 연간 벡터를 지원합니다. 표 페이지에서 벡터 번호를 복사하기 전에 카탈로그 결과의 주기를 확인하세요.

형식이 잘못된 벡터 ID는 400 invalid_series_id를 반환합니다. 상세 설명에는 캐나다 통계청 시계열 ID가 v<vector number> 형식이라고 나옵니다. statcan:v41690973과 같은 전체 ID를 id 매개변수로 전달하세요. 오류 처리는 API 오류를 확인하세요.

값의 상태는 어떻게 확인하나요?

각 관측값의 선택적 status 필드를 확인하세요. 값의 상태가 provisional 또는 estimated 등일 때 포함됩니다. 계산에서도 이 맥락이 유지되도록 기간 및 값과 함께 보존하세요.

released_on이 있으면 유지하고, 데이터 조회 시각에는 fetched_at을 사용하세요. 원본 출처에 연결할 수 없어 Narwhal이 마지막으로 보관한 사본을 제공할 때만 응답에 stale: true가 설정됩니다. 관측값의 상태와 응답의 최신성은 서로 다른 속성입니다.