캘린더 구독 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` 거짓으로.
`scope`	비어 있지 않은 선택적 범위 식별자(최대 64자)

공휴일 전용 구독은 경제 지표 발표를 지원하는 국가 목록에 없는 국가라도 공휴일 데이터가 게시되어 있으면 이용할 수 있습니다.

응답 예시

응답 예시입니다. 구독 생성 응답에서 토큰 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을 비밀로 취급하십시오. 이를 가진 사람은 누구나 만료 또는 취소될 때까지 피드를 읽을 수 있습니다.

Bearer 키와 함께 사용할 요청: DELETE /v1/calendars/subscriptions/{subscription_id} —구독을 취소합니다. 만료되었거나 취소되었거나 알 수 없는 피드 토큰은 404를 반환합니다. 피드에는 API 키가 절대 포함되지 않습니다.