経済指標 スケジュール：発表前に時刻、対象期間、前回値を確認する

1か国の指標を1件調べる

GET /v1/economics/calendar で、国と日付を指定してカレンダーを取得します。このリクエストは日本の 11月20日を尋ねます。

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/calendar?countries=JPN&start_date=2026-11-20&end_date=2026-11-20&limit=100"

{
  "releases": [
    {
      "release_id": "6c00d274-da35-4ed4-bcc1-574101544a03",
      "revision": 3,
      "country": "JPN",
      "series_id": "jpn-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-10",
      "status": "scheduled",
      "at": "2026-11-19T23:30:00Z",
      "timezone": "Asia/Tokyo",
      "values": [
        {
          "measure": "core_core_cpi_yoy",
          "concept": "cpi_ex_fresh_food_energy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.4",
          "not_seasonally_adjusted": true
        },
        {
          "measure": "core_cpi_yoy",
          "concept": "cpi_ex_fresh_food",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.1",
          "not_seasonally_adjusted": true
        },
        {
          "measure": "cpi_mom",
          "concept": "cpi",
          "unit": "percent",
          "transformation": "month_over_month",
          "previous": "0.4"
        },
        {
          "measure": "cpi_yoy",
          "concept": "cpi",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.1",
          "not_seasonally_adjusted": true
        }
      ]
    }
  ],
  "next_cursor": null
}

この指標は period が 2026-10 の日本の消費者物価で、数値は10月分です。at は 2026-11-19T23:30:00Z、timezone は Asia/Tokyo です。values の各項目には measure と previous(前回値)があり、cpi_yoy の前回値は 2.1、cpi_mom の前回値は 0.4 です。数値は文字列なので、比較する前に数値へ変換してください。

transformation は数値の算出方法を示します。cpi_yoy は year_over_year、cpi_mom は month_over_month です。4つの指標のうち3つに not_seasonally_adjusted: true が付いているので、予想値と前回値を比べる前にこのフラグを確認してください。

リクエストでは 11月20日を指定しましたが、UTC では at が 11月19日になっています。日付の範囲は発表元の現地カレンダーに従い、UTC の 23:30 は東京では翌朝の 08:30 だからです。

次に注目度の高い指標を選び、時刻を変換する

カレンダーには重要度の評価がないため、何を注目度が高いとみなすかは自分で決めます。以下のスクリプトは topic の値のウォッチリストを使い、まだ scheduled で at 時刻を持つ発表だけを残し、並べ替えて先頭の3件を取ります。

1. ウォッチリストと自分のタイムゾーンを設定する 取引している分野を集合に入れます。スクリプトは消費者物価、GDP、労働力、雇用、賃金を監視し、トレーダーのタイムゾーンとして America/New_York に変換します。
2. 期間をリクエストする 1か国と日付の範囲を指定します。スクリプトは日本の 11月16日から29日を limit 100 で取得します。
3. 絞り込み、並べ替え、変換 datetime.fromisoformat が UTC のタイムスタンプを読み取ります。astimezone はそれを timezone フィールドの発表元のタイムゾーンと、トレーダーのタイムゾーンに変換します。前回値は values[].previous から取ります。
   Python、次に注目する3件の指標

   import os
   from datetime import datetime
   from zoneinfo import ZoneInfo
   import requests
   
   BASE = "https://api.narwhalapi.com"
   
   WATCH = {"consumer_prices", "gdp", "labour_force", "employment", "wages"}
   MY_TZ = ZoneInfo("America/New_York")
   
   r = requests.get(
       f"{BASE}/v1/economics/calendar",
       params={"countries": "JPN", "start_date": "2026-11-16", "end_date": "2026-11-29", "limit": 100},
       headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
       timeout=10,
   )
   r.raise_for_status()
   
   picked = [
       x for x in r.json()["releases"]
       if x.get("topic") in WATCH and x["status"] == "scheduled" and "at" in x
   ]
   for x in sorted(picked, key=lambda x: x["at"])[:3]:
       utc = datetime.fromisoformat(x["at"].replace("Z", "+00:00"))
       local = utc.astimezone(ZoneInfo(x["timezone"]))
       mine = utc.astimezone(MY_TZ)
       prev = ", ".join(f"{v['measure']} {v['previous']}" for v in x["values"] if "previous" in v)
       print(x["name"], x["period"])
       print("  UTC  ", utc.strftime("%a %d %b %H:%M"))
       print("  Tokyo", local.strftime("%a %d %b %H:%M"))
       print("  NYC  ", mine.strftime("%a %d %b %H:%M"))
       print("  previous:", prev or "none listed")

GDP 2026-Q3
  UTC   Sun 15 Nov 23:50
  Tokyo Mon 16 Nov 08:50
  NYC   Sun 15 Nov 18:50
  previous: none listed
Consumer prices 2026-10
  UTC   Thu 19 Nov 23:30
  Tokyo Fri 20 Nov 08:30
  NYC   Thu 19 Nov 18:30
  previous: core_core_cpi_yoy 2.4, core_cpi_yoy 2.1, cpi_mom 0.4, cpi_yoy 2.1
Wages and earnings 2026-09
  UTC   Tue 24 Nov 23:30
  Tokyo Wed 25 Nov 08:30
  NYC   Tue 24 Nov 18:30
  previous: average_cash_earnings_yoy 3.9, real_wages_yoy 1.6

GDP の行は、ウィンドウの開始が 11月16日なのに UTC では Sun 15 Nov 23:50 と表示されます。東京では 11月16日(月)の 08:50 だからです。前回値の行は「none listed」と出ますが、この GDP の発表は values が空のリストだからです。スクリプトは previous がないときにプレースホルダーを出力するので、1つ数値が欠けてもループは止まりません。

1つの時点を3つの時計で見る

東京は UTC より9時間進んでおり、23:30 に9時間を足すと翌日の 08:30 です。この日付のニューヨークは UTC より5時間遅れているので、23:30 から5時間引くと 18:30 です。スクリプトは夏時間の規則を自動で適用する zoneinfo を使うので、オフセットを保存しておく必要はありません。

あとで同じ指標をもう一度読む

すべての発表に release_id があります。GET /v1/economics/calendar/{release_id} はその1件を返し、version と observed_at の2つのフィールドが加わります。observed_at は、Narwhal が発表元のカレンダーでその発表を最後に確認した時刻です。期間全体をダウンロードせずに、ウォッチ中の発表の行を更新するのに使います。

status は、数値が公表されると scheduled から published に変わり、値に previous と並んで actual が入ることがあります。発表の一部には stage もあり、flash、advance、preliminary、final などがあります。最初の推計を確定値と取り違えないよう、名前の横に表示してください。

カレンダーは指標を重要度で並べていますか。

いいえ。発表には prices、labour、gdp などの family と、consumer_prices などの topic が付きますが、評価はありません。ウォッチリストはこの2つのフィールドから作り、トピックを持たない発表もあるため .get("topic") を使ってください。

なぜ前回値のない指標があるのですか。

values は必ず存在しますが、空のリストになることがあり、指標によっては previous がないこともあります。上の日本の GDP の発表は空のリストでした。発表が以前の数値を改定する場合、previous_revised_from に置き換えられた数値が入ります。

正確な時刻のない指標はどうなりますか。

その場合 at はなく、代わりに date、between、by のいずれかが入ります。スクリプトは変換にタイムスタンプが必要なのでそれらを飛ばします。そうした行も表示したいときは、時刻を推測せず date を出力して時刻を不明と記してください。