日历订阅 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。至少一个必须保持为 true。
`families`	可选发布系列： `gdp`, `prices`, `labour`, `trade`, `yield_curve`。省略或使用空列表表示所有系列。对于仅假日订阅，将 `include_releases` 设为 false。
`scope`	可选的非空范围标识符，最长64个字符。

仅包含假日的订阅也可使用经济数据发布所覆盖国家之外、已发布假日数据的国家。

响应示例

示例响应。创建订阅时请保存令牌 URL；创建响应只返回一次该 URL。

已创建

{
  "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 密钥。