在經濟數據發布前收到提醒

使用 API

1. 取得你的 API 金鑰 取得免費 API 金鑰，並存放在環境變數 NARWHAL_API_KEY 中。請求發送至 https://api.narwhalapi.com，並帶上 Authorization: Bearer YOUR_KEY；範例會從該變數讀取金鑰。
2. 建立行事曆訂閱源 帶上國家與日期範圍，發送 POST /v1/calendars/subscriptions。範例請求的是 USA、prices 與 policy_rate 系列、不含假日，時間範圍為 2026 年 10 月 24 日至 2027 年 10 月 23 日。
   curl，建立行事曆訂閱源

   curl -s -X POST https://api.narwhalapi.com/v1/calendars/subscriptions \
     -H "Authorization: Bearer $NARWHAL_API_KEY" -H "Content-Type: application/json" \
     -d '{"countries":["USA"],"start_date":"2026-10-24","end_date":"2027-10-23",
         "include_holidays":false,"families":["prices","policy_rate"]}'

3. 儲存訂閱資訊 請保存回應中的 subscription_id、url 與 expires_at。.ics 網址只會回傳一次，請務必保存好，並把它當作機密。
4. 用每日腳本傳送電子郵件或聊天訊息 要向團隊頻道發送提醒，請每天執行一次這支腳本，並透過聊天工具的傳入 Webhook 傳送它的輸出。你也可以用自己的程式碼把輸出傳送到電子郵件。
   Python，未來 24 小時內將要公布的資料

   import os, sys
   from datetime import datetime, timedelta, timezone
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   COUNTRIES = ["USA", "GBR", "JPN"]
   AHEAD = timedelta(hours=24)
   
   
   def upcoming():
       now = datetime.now(timezone.utc)
       r = requests.get(
           "https://api.narwhalapi.com/v1/economics/calendar",
           headers=HEADERS,
           timeout=10,
           params={
               "countries": COUNTRIES,
               "start_date": now.date().isoformat(),
               "end_date": (now + AHEAD).date().isoformat(),
               "limit": 100,
           },
       )
       r.raise_for_status()
       for x in r.json()["releases"]:
           if x["status"] == "scheduled" and "at" in x:
               at = datetime.fromisoformat(x["at"].replace("Z", "+00:00"))
               if now <= at <= now + AHEAD:
                   yield x, at
   
   
   for release, at in upcoming():
       print(
           f"{release['country']} {release['name']} ({release.get('period')}) "
           f"at {at:%Y-%m-%d %H:%M} UTC"
       )

請提供 1 至 50 個 alpha-3 國家代碼，以及相隔不超過 366 天的起訖日期（含首尾）。選用的 families 篩選器最多接受 5 個系列。

有效期為建立後 365 天；2026 年 10 月 24 日建立的訂閱源會在 2027 年 10 月 24 日到期。include_releases 與 include_holidays 預設都為 true，且至少有一個必須為 true。範例關閉了假日，保留公布資料。

腳本讀取 USA、GBR 與 JPN 的行事曆，然後輸出 at 時間在未來 24 小時內的已排定公布。每行輸出包含國家、公布名稱、統計期與 UTC 時間。如果沒有即將公布的資料，則不輸出任何內容。

腳本的時鐘與公布時間戳記都使用 UTC。它的請求涵蓋從執行時刻起到未來 24 小時結束的行事曆日期，上限為 100 筆。

時間戳記比較包含兩端邊界。沒有 at 欄位的公布，以及狀態不是 scheduled 的公布，都會被排除。請求在讀取回應之前會呼叫 raise_for_status()，因此出現 HTTP 錯誤時，腳本會在輸出公布資料之前停止。

無需程式碼設定提醒

把訂閱源網址作為訂閱行事曆加入你的行事曆應用程式。在 Google 日曆中，進入「其他日曆」>「透過網址新增」，然後貼上 .ics 網址。Outlook 與 Apple 行事曆也提供訂閱網路行事曆的選項。請使用訂閱請求回傳的網址。

範例訂閱源包含 prices 與 policy_rate 系列的 USA 公布資料。若要同時包含假日，請在建立請求中把 include_holidays 設為 true。若只想要假日，請把 include_releases 設為 false，並讓 include_holidays 維持為 true。

為該行事曆設定預設通知，例如在公布前 1 小時提醒。提醒設定屬於行事曆應用程式。建立訂閱源會得到訂閱網址；把它加入應用程式並設定通知，才能讓它成為你個人的提醒。

關於訂閱源請求，請參閱行事曆訂閱文件。如果想依自己所在的時區查看公布時間，請參閱將公布時間轉換為你的時區。

各種情況適合的方式

Webhook 會透過 release.scheduled、release.rescheduled 與 release.cancelled 回報公布被新增、改期或取消，並透過 dataset.published 回報資料已發布。它們不會在公布前依計時觸發。要提前提醒，請使用行事曆提醒或腳本；需要這些變更或發布事件時，請使用 Webhook。

公布改期後，訂閱源會更新嗎？

會。行事曆應用程式會依自己的排程重新取得訂閱源，且該訂閱源支援 ETag 重新整理。延遲來自行事曆用戶端。日期變更會在應用程式重新整理訂閱源時同步到所訂閱的行事曆，更新頻率由應用程式決定。

如何停止行事曆訂閱源？

呼叫 DELETE /v1/calendars/subscriptions/{subscription_id} 即可撤銷。回應為 204，訂閱源隨即停止。該請求使用建立回應中保存的 subscription_id；訂閱源網址則是你提供給行事曆應用程式的那個值。

行事曆訂閱源會用掉多少次請求？

建立訂閱源用 1 次請求，撤銷也用 1 次請求。行事曆應用程式之後的取得不會使用你的 Bearer 金鑰。雖然行事曆應用程式用這個網址取得行事曆，但仍請對訂閱源網址保密。

實例：美國 CPI 提前 1 小時的提醒

從 2026-11-10T13:30:00Z 公布的美國 CPI 開始。13:30 UTC 減去 1 小時，得到提醒時間：2026 年 11 月 10 日 12:30 UTC。把所訂閱行事曆的預設通知設定為事件前 1 小時。

在紐約，同一提醒落在 2026 年 11 月 10 日 07:30 EST；在雅加達則是 2026 年 11 月 10 日 19:30。這些是提醒的當地時間，公布本身在當天的 13:30 UTC。