経済リリースの前に通知を受け取る

APIを使う方法

1. APIキーを取得 無料の API キーを取得し、環境変数 NARWHAL_API_KEY に保存します。リクエストは Authorization: Bearer YOUR_KEY を付けて https://api.narwhalapi.com に送ります。例ではこの変数からキーを読み取ります。
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 の URL は一度しか返されないので、必ず保管し、秘密として扱ってください。
4. メールやチャット向けに毎日のスクリプトを使う チームのチャンネルに通知するには、このスクリプトを 1 日 1 回実行し、出力をチャットツールの受信 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 エラーが起きると発表を表示する前に停止します。

コードなしで通知を設定する

フィードの URL を購読するカレンダーとして、カレンダーアプリに追加します。Google カレンダーでは、他のカレンダー > URL で追加 を開き、.ics の URL を貼り付けます。Outlook と Apple カレンダーにも、ウェブ上のカレンダーを購読するオプションがあります。購読リクエストで返された URL を使ってください。

この例のフィードには、prices と policy_rate ファミリーの USA の発表が含まれます。祝日も含めるには、作成リクエストで include_holidays を true にします。祝日だけをリクエストするには、include_releases を false にし、include_holidays を true のままにします。

そのカレンダーの既定の通知を設定します（例：発表の 1 時間前）。通知の設定はカレンダーアプリ側にあります。フィードを作成すると購読用 URL が得られ、それをアプリに追加して通知を設定する手順が、個人用の通知を完成させます。

フィードのリクエストについては、カレンダー購読のドキュメントを参照してください。発表時刻を自分のタイムゾーンで見たい場合は、発表時刻を自分のタイムゾーンに変換するを参照してください。

状況に応じた方法の選び方

Webhook は、発表が追加、変更、キャンセルされたことを release.scheduled、release.rescheduled、release.cancelled で通知します。公開されたデータは dataset.published で通知されます。発表の前にタイマーで発火することはありません。事前の通知にはカレンダーの通知かスクリプトを使い、これらの変更や公開のイベントが必要なときはWebhookを使ってください。

発表が動いたら、フィードも更新されますか？

はい。カレンダーアプリは独自のスケジュールでフィードを再取得し、フィードは ETag による更新に対応しています。遅れはカレンダークライアント側で生じます。日付の変更は、アプリがフィードを更新した時点で購読中のカレンダーに反映され、その頻度はアプリが決めます。

カレンダーフィードを止めるには？

DELETE /v1/calendars/subscriptions/{subscription_id} を呼び出して取り消します。レスポンスは 204 で、フィードは停止します。このリクエストには、作成時のレスポンスで保存した subscription_id を使います。フィードの URL は、カレンダーアプリに渡した値です。

カレンダーフィードは何リクエスト使いますか？

フィードの作成は 1 リクエスト、取り消しも 1 リクエストです。カレンダーアプリがその後に行う取得では、Bearer キーは使われません。カレンダーアプリがこの URL でカレンダーを取得するとはいえ、フィードの URL は秘密にしてください。

実例：米国 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 です。