IDでカナダ統計局の表を取得する

APIを使う方法

1. APIキーを設定 Narwhal APIキーをNARWHAL_API_KEYに設定し、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をカンマで区切り、1つのidsパラメーターとして最新値ルートに送信してください。1回の一括リクエストには異なる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を使用します。出力結果は小数点以下2桁に丸めます。
   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%です。小数点以下2桁に丸めると、結果は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を使用してください。レスポンスにstale: trueが含まれるのは、ソースに接続できず、Narwhalが最後に保持したコピーを提供する場合だけです。観測値のステータスとレスポンスの鮮度は、それぞれ別の性質を示します。