在公布之前查看數據的公布時間、所屬期間和前值

查詢某個國家的一筆數據公布

用 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。四項指標中有三項帶有 not_seasonally_adjusted: true，所以在拿預測值與前值比較之前，請先檢查這個標記。

請求指定的是 11 月 20 日，但 at 按 UTC 是 11 月 19 日。日期範圍按發布機構的當地日曆計算，而 UTC 的 23:30 在東京是隔天早上 08:30。

挑出接下來的高關注度數據公布並轉換時間

日曆沒有重要性評級，所以哪些算高關注度由你自己決定。下面的腳本使用一份由 topic 值組成的關注清單，只保留仍為 scheduled 且帶有 at 時間的公布，排序後取前三筆。

1. 設定關注清單和你自己的時區 把你交易的主題放進一個集合。腳本關注消費者物價、GDP、勞動力、就業和薪資，並換算成交易員所在的時區 America/New_York。
2. 請求一段時間範圍 指定一個國家和一段日期範圍。腳本取日本 11 月 16 日至 29 日，limit 為 100。
3. 過濾、排序與轉換 datetime.fromisoformat 讀取 UTC 時間戳記，astimezone 把它轉換成 timezone 欄位給出的發布機構時區和交易員所在的時區。前值取自 values[].previous。
   Python，接下來關注的三筆數據公布

   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 這一列在 UTC 下顯示為 Sun 15 Nov 23:50，儘管範圍從 11 月 16 日開始，因為它在東京是 11 月 16 日週一 08:50。它的前值一行顯示「none listed」，是因為這筆 GDP 公布的 values 清單為空。只要沒有 previous，腳本就輸出一個佔位符，所以缺少一個數值不會讓迴圈中斷。

同一時刻在三個時鐘上的讀數

東京比 UTC 快 9 小時，23:30 加 9 小時就是隔天 08:30。那一天紐約比 UTC 慢 5 小時，23:30 減 5 小時就是 18:30。腳本使用 zoneinfo，它會自動套用日光節約時間規則，所以無需儲存偏移量。

稍後再次讀取同一筆公布

每筆公布都有一個 release_id。GET /v1/economics/calendar/{release_id} 會回傳這一筆公布，並多出 version 和 observed_at 兩個欄位，後者表示 Narwhal 最近一次在發布機構日曆中看到這筆公布的時間。用它來更新你正在關注的那筆公布的列，而不必下載整個範圍的資料。

數據公布後，status 會從 scheduled 變為 published，此時數值裡可以在 previous 之外帶有 actual。有些公布還帶有 stage，例如 flash、advance、preliminary 或 final。把它顯示在名稱旁邊，免得把初步估計誤當作最終值。

日曆會按重要性替數據公布排序嗎？

不會。公布帶有 prices、labour 或 gdp 之類的 family，以及 consumer_prices 之類的 topic，但沒有評級。請用這兩個欄位建立關注清單，並使用 .get("topic")，因為有些公布沒有 topic。

為什麼有些數據公布沒有前值？

values 一定會存在，但可能是空清單，某項指標也可能沒有 previous。上面的日本 GDP 公布就是空清單。當一次公布修訂了先前的數字時，previous_revised_from 保存被取代的數字。

如果某筆公布沒有確切時間怎麼辦？

這類公布沒有 at，而是帶有 date、between 或 by 之一。腳本需要時間戳記才能轉換，所以會跳過它們。如果你也想看到這些列，就輸出 date，並把時間標為未知，不要憑空猜一個。