建立經濟行事曆

使用 API

發布日期請使用經濟日曆。每個發布項都有時間、國家和名稱欄位，以及所屬期間、主題、狀態和時區。如果你的產品或儀表板需要比列印出來的時程更多的細節，就把這些欄位與發布項一起儲存。

1. 設定你的 API 金鑰 取得免費金鑰，並儲存在 NARWHAL_API_KEY 環境變數中。腳本會讀取該變數，並把金鑰以 Authorization: Bearer YOUR_KEY 的形式傳送到 https://api.narwhalapi.com。Narwhal 的 REST 和 MCP 使用同一把金鑰。
2. 選擇國家和日期 重複傳入 countries 參數，並帶上 start_date 和 end_date。範例使用 USA、GBR 和 JPN，日期為 2026 年 11 月 9 日至 13 日。想要不同的時程時，修改國家清單和日期參數即可；請求仍指向 /v1/economics/calendar。
3. 取得並排序發布項 在環境變數中準備好金鑰後執行 Python 腳本。它會收集所有分頁中的發布項，篩選出帶有 at 的記錄，並把時間、國家和名稱一起排序。印出的時程使用 UTC 時間，最後給出所請求日期範圍內的發布數量。
   Python：三個國家一週的發布項

   import os
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   def calendar(countries, start, end):
       cursor = None
       while True:
           params = {
               "countries": countries,
               "start_date": start,
               "end_date": end,
               "limit": 100,
           }
           if cursor:
               params["cursor"] = cursor
           r = requests.get(
               "https://api.narwhalapi.com/v1/economics/calendar",
               params=params,
               headers=HEADERS,
               timeout=10,
           )
           r.raise_for_status()
           body = r.json()
           yield from body["releases"]
           cursor = body.get("next_cursor")
           if not cursor:
               return
   
   
   rows = sorted(
       (x["at"], x["country"], x["name"])
       for x in calendar(["USA", "GBR", "JPN"], "2026-11-09", "2026-11-13")
       if "at" in x
   )
   for at, country, name in rows:
       print(at, country, name)
   print(len(rows), "releases")

4. 選擇要顯示的欄位 在更完整的日曆中顯示 at（UTC）、country、name、period、topic、status 和 timezone。腳本只印出時間、國家和名稱。需要區分同一發布的不同版本時，請保留 stage。在數值公布之前 values 陣列為空，所以已排定的發布可以在有數值之前就出現。

使用網站、日曆應用程式或試算表

要在 Narwhal 網站上查看發布項，請開啟經濟日曆。每個國家都有各自的經濟日曆頁面，想不寫請求直接查看某個國家的時程時，這是最直接的方式。

日曆訂閱源會在你的日曆應用程式裡顯示同樣的發布項。請參照在經濟資料發布前收到提醒了解這種方式。如果你偏好試算表，它可以儲存腳本的輸出：UTC 時間、國家和發布名稱。試算表方式從 API 輸出開始；想不寫程式碼查看時程時，可以使用網站和訂閱源。

各種情況適合的方式

為什麼英國的 GDP 出現了兩次？

同一發布的兩個版本可能在同一時間發布，用 stage 可以區分。例如，首次估計值和月度資料可能排定在同一時間。該欄位還能區分快速估計、初值、首次和終值等版本，所以只看發布名稱和時間，各版本可能看起來一模一樣。

在名稱旁邊顯示 stage 或 release_id，以區分各個項目。2026 年 11 月 12 日 07:00 UTC，英國的時程中包含兩次 GDP。顯示該時程時要保留這兩個項目，並在每個名稱旁邊顯示版本或識別碼。

一次請求會回傳多少個發布項？

每頁最多回傳 100 個發布項。用 limit 設定頁大小，並傳入 cursor 繼續讀取結果。一頁只是所請求時程的一部分；請透過 next_cursor 判斷同一國家和日期範圍內是否還有更多發布項需要收集。

一直讀取到 next_cursor 為 null 或為空為止。如果 API 回傳 409 cursor_expired，請不帶游標重新發起請求。重新請求時要保持原來的國家和日期選擇，這樣才能從頭取得你所要的時程。

日曆中可以包含哪些國家？

省略 countries 會回傳所有已涵蓋的國家，也可以傳入最多 50 個國家代碼。歐元區請使用 EMU。

Python 範例傳入了國家清單，它會變成請求中重複的 countries 參數。想要涵蓋所有國家的日曆時，把該參數從請求中去掉。保留日期範圍，並先收集全部分頁，再依 UTC 時間對發布項排序。

計算範例：2026 年 11 月 9 日至 13 日

對於 2026 年 11 月 9 日至 13 日，先數美國的項目：批發貿易、消費者物價、薪資與所得、初領失業救濟金人數、石油庫存、公共財政和生產者物價，美國共 7 項。日本在同一日期範圍內有家庭支出和國際收支 2 項。

再單獨數英國的 GDP 項目。加上營建業產出、商品與服務貿易、工業生產和服務業產出，英國在 2026 年 11 月 9 日至 13 日共 6 項。把各國的數量相加，就得到該時程的總數。

按日期順序閱讀 UTC 時間。2026 年 11 月 9 日，美國批發貿易在 15:00，日本家庭支出在 23:30，日本國際收支在 23:50。2026 年 11 月 10 日，美國消費者物價與薪資與所得同在 13:30。2026 年 11 月 12 日，美國初領失業救濟金人數在 13:30，石油庫存在 17:00，公共財政在 19:00。美國生產者物價在 2026 年 11 月 13 日 13:30。

2026 年 11 月 9 日至 13 日最繁忙的一個小時是 11 月 12 日 07:00 UTC，英國的 6 項發布全部集中在這一刻。在排序後的時程中，這一組包含兩個版本的 GDP，以及營建業產出、商品與服務貿易、工業生產和服務業產出。