カレンダー購読 API リファレンス

経済指標発表、祝日、またはその両方の取り消し可能な ICS フィードを作成します。

購読を作成する

作成リクエストには Narwhal Bearer キーを使用します。製品概要→

POST /v1/calendars/subscriptions

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'

リクエストフィールド

フィールド	規則
`countries`	1～50個の ISO alpha-3 国コードを指定する必須リスト。
`start_date / end_date`	開始日と終了日を含む必須の日付範囲。1900～2200年の範囲内で、両日の日付の差は最大366日です。
`include_releases / include_holidays`	オプションのブール値。どちらもデフォルトは true です。少なくとも 1 つは true のままでなければなりません。
`families`	任意で指定できる経済指標の発表カテゴリ： `gdp`, `prices`, `labour`, `trade`, `yield_curve`。すべてのカテゴリを含めるには、省略するか空のリストを指定します。祝日のみのフィードにする場合の設定： `include_releases` 偽に。
`scope`	オプションの空ではないスコープ識別子 (最大 64 文字)。

祝日のみの購読では、経済指標発表の対象国に含まれない国でも、祝日データが公開されていれば指定できます。

レスポンスの例

レスポンスの例です。購読の作成時にトークン URL を保存してください。作成レスポンスで返されるのは1回だけです。

作成されました

{
  "subscription_id": "example-subscription",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2026-12-31T23:59:59Z",
  "refresh_note": "calendar clients control refresh latency"
}

subscription_id は、購読解除の対象レコードを識別します。 expires_at は有効期限のタイムスタンプです。更新の反映までの遅延はカレンダークライアント側で制御されます。

更新と購読解除

カレンダークライアントによる取得リクエストは GET /v1/calendars/subscriptions/{token}.icsです。フィードは ETag を使った更新に対応しています。トークン URL はシークレットとして扱ってください。この URL を知っている人は誰でも、有効期限が切れるか購読が解除されるまでフィードを読み取れます。

Bearer キーを付けて DELETE /v1/calendars/subscriptions/{subscription_id} を実行すると購読を解除できます。期限切れ、失効済み、または未知のフィードトークンには404を返します。フィードに APIキーが含まれることはありません。