경제 지표 발표 API 레퍼런스

예정된 발표를 조회하고 원래 일정의 정밀도를 유지한 불변 게시 버전을 가져옵니다.

요청

두 작업 모두 Narwhal Bearer 키를 사용합니다. 제품 개요 →

발표 목록 조회

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31&limit=25" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

GET /v1/economics/calendar/{release_id} 요청은 발표 항목 하나를 조회합니다. 추가할 매개변수: version_id —변경되지 않는 특정 버전을 선택할 때 사용하세요.

매개변수

매개변수	규칙
`countries`	선택적 ISO alpha-3 코드. 여러 국가에 대해 쿼리 매개변수를 반복합니다. 최대 50개.
`start_date / end_date`	선택적 날짜 범위로 시작일과 종료일을 모두 포함합니다. 기본값은 오늘의 30일 전부터 335일 후까지이며, 범위는 최대 366일입니다.
`view`	`view`는 발표마다 간략한 항목을 반환하는 `compact`(기본값) 또는 `GET /v1/economics/calendar/{release_id}`가 반환하는 것과 동일한 객체를 반환하는 `full`입니다. 전체 보기에는 버전, 수정, 일정 세부 정보, 값 타임스탬프, 계절 조정 및 수정 전 값 등 모든 필드가 포함됩니다.
`limit / cursor`	페이지 크기는 1~100이며 기본값은 100입니다. 다음 페이지 조회에 사용할 값: `next_cursor` 및 기존과 동일한 필터입니다.
`release_id / version_id`	발표 상세 조회에는 UUID 형식의 경로 ID와 선택적 UUID 버전 ID를 사용합니다.

응답 예시

목록 응답 예시입니다. 상세 조회 작업은 동일한 필드로 구성된 발표 객체 하나를 반환합니다.

200 OK

{
  "status": "ok",
  "snapshot": "calendar-snapshot-20260914",
  "as_of": "2026-09-14T08:00:00Z",
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "series_id": "usa-consumer-prices",
      "country": "USA",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "title": "Consumer Price Index",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York"
    }
  ],
  "next_cursor": null
}

필드	규칙
`title / name`	`title`은 제공 기관이 직접 붙인 제목으로, 해당 기관의 언어와 표현을 그대로 사용합니다. `name`은 `Producer prices`나 `Labour force survey`처럼 정해진 목록에서 선택되는 Narwhal의 표준 영어 이름이며 날짜를 포함하지 않습니다.
`series_id`	`series_id`는 `tur-producer-prices`처럼 모든 회차의 발표가 공유하는, Narwhal이 시계열에 부여한 영구 ID입니다. 시계열이 아직 분류되지 않은 경우에는 표시되지 않습니다.
`topic`	`topic`은 시계열이 무엇을 측정하는지 나타내며 `consumer_prices`, `labour_force`, `gdp`, `merchandise_trade`, `policy_rate`처럼 국가 간에 일관됩니다. 시계열이 아직 분류되지 않은 경우에는 없으며, 새 주제가 추가될 수 있습니다.
`stage`	`stage`는 발표에 포함된 해당 기간 수치가 어느 회차인지 나타냅니다: `flash`, `advance`, `first`, `second`, `third`, `preliminary` 또는 `final`. 한 번만 발표되는 경우에는 표시되지 않습니다.
`at / date / between / by`	날짜가 정해지면 시점 필드 하나가 표시됩니다. `at`은 정확한 발표 시각, `date`는 시각이 정해지지 않은 발표일, `between`은 `[from, to]` 형식의 양 끝을 포함하는 가능한 날짜 범위, `by`는 발표가 가능한 마지막 날로, 약속된 날이 아니라 기한입니다. 모든 타임스탬프는 UTC이며, `timezone`은 제공 기관의 IANA 시간대이고, 전체 보기에서 `schedule.local_date`는 해당 시간대 기준 발표일입니다.
`period / values`	`period`는 발표가 다루는 기간입니다. `values`는 수치가 발표된 후 표시되며 `measure`, `unit`, `transformation`, `actual`, `previous`를 포함하고, 금액에는 `currency`와 `scale`도 포함됩니다.

목록은 기본적으로 간략한 항목을 반환하며, 필드는 값이 있을 때만 표시됩니다. 모든 필드를 받으려면 view=full을 전달하세요. 일부 제공 기관이 발표 옆에 함께 게시하는 연구 기사와 반복 데이터 세트는 포함되지 않습니다.

일정 및 상태 의미

family 중 하나입니다 gdp, prices, labour, trade, yield_curve, policy_rate, activity, survey, housing, money, 또는 public_finance. status 다음입니다 scheduled, published, 또는 cancelled.

일정 precision 다음입니다 exact, date, estimated_range, deadline, 또는 unknown. 출처의 시간대와 제공된 범위 경계를 유지하세요. 마감일은 발표 가능한 최종 날짜이며, 확정된 발표일이 아닙니다. observed_at 및 officially_published_at 필드는 서로 다른 사건의 시점을 나타내며 null일 수 있습니다.

취소 및 일정 변경은 명시적인 버전으로 유지됩니다. 알 수 없는 시간을 자정으로 채우지 마십시오.

Narwhal 캘린더에 있는 유럽중앙은행과 캐나다은행의 발표 날짜와 시간은 각 은행 웹사이트에서 가져오며, 해당 사이트에서 무료로 확인할 수 있습니다. 모든 응답에서 각 유럽중앙은행 발표 항목에는 유럽중앙은행을 출처로 명시하고 해당 정보를 https://www.ecb.europa.eu 에서 무료로 이용할 수 있음을 알리는 notice 필드가 포함됩니다.

경제 지표 발표 일정의 데이터 범위

아래 국가의 일부 공식 발표 일정을 이용할 수 있습니다. 제공 범위는 발표 기관과 경제 시계열에 따라 다르며, 목록에 포함되어 있어도 모든 지표에 일정이 있는 것은 아닙니다. 목록 요청을 국가와 날짜 범위로 필터링하여 해당 스냅샷에 포함된 발표를 확인하세요.

발표 일정이 있는 국가 · 35

빈 결과는 해당 스냅샷에 쿼리와 일치하는 발표가 없다는 뜻입니다. 발표 기관에 예정된 발표가 없음을 보장하지는 않습니다. 공휴일과 은행 휴무일은 별도의 캘린더 데이터셋입니다.

수치

경제지표 발표 일정 API의 각 발표에는 indicators 배열이 포함됩니다. 각 지표에는 발표 기관이 공표한 수치가 담깁니다. actual은 해당 발표의 대상 기간 수치이며, previous는 그 직전 기간의 수치입니다. Narwhal은 이 수치를 계산하지 않습니다. 아래 필드는 각 수치의 기간, 단위, 변환 방식, 연율 환산 여부를 설명합니다.

필드	규칙
`period / previous_period`	`period`는 수치의 대상 기간을 나타내며, 월(`2026-08`), 분기(`2026-Q3`), 지정된 날짜에 끝나는 주(`2026-09-26`), 또는 이동 3개월 기간(`2026-06/2026-08`, 첫 달과 마지막 달) 중 하나의 형식입니다. `previous_period`는 같은 형식으로 한 단계 이전 기간을 나타냅니다. 주간 발표에서는 계속 실업수당 청구 건수처럼 해당 발표의 대상 주보다 한 주 전을 다루는 수치가 포함될 수 있습니다.
`unit`	`unit`은 `percent`, `index`(`2015=100`과 같은 `index_base` 포함), `thousands`, `currency`, `ratio`(예: 구직자 수 대비 구인 수의 비율), 또는 `balance`(설문 응답의 순차이를 백분율이 아닌 포인트로 표시)입니다.
`currency / scale`	`currency`(ISO 4217 코드)와 `scale`(`units`, `thousands`, `millions`, `hundred_millions` 또는 `billions`)은 `unit`이 `currency`일 때만 표시됩니다. 수치는 발행자가 표기한 배율을 따릅니다.
`transformation`	`transformation`은 `level`, `month_over_month`, `year_over_year`, `quarter_over_quarter`, `three_month_on_three_month`, 또는 `change`(고용 증감처럼 수준의 차이를 천 단위로 표시한 값)입니다.
`annualization`	`annualization`은 항상 포함되며, `annualized`(예: 연율로 표시한 미국 GDP 성장률) 또는 `not_annualized`입니다.
`actual / previous`	`actual`은 해당 발표의 대상 기간 수치이며, `previous`는 그 직전 기간의 수치입니다. 둘 다 발표 기관이 공표한 값이며, Narwhal은 이를 계산하지 않습니다. 발표에 명시되지 않은 경우 `previous`는 `null`일 수 있으며, 이 경우 다음 발표에는 앞선 `actual`이 `previous`로 포함됩니다.

시간이 지나면서 이 필드에 새로운 값이 추가될 수 있으므로, 클라이언트는 인식하지 못하는 값도 허용해야 합니다.