전체 문서 탐색

경제 캘린더 API 레퍼런스 안내

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

요청

경제 출시 일정 탐색 →

두 작업 모두 Narwhal Bearer 키를 사용합니다. Each successful request costs one call on the Calendars API code, $2 per 1,000 calls. 제품 개요 →

발표 목록 조회
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일입니다.
limit / cursor페이지 크기는 1~100이며 기본값은 100입니다. 다음 페이지 조회에 사용할 값: next_cursor 및 기존과 동일한 필터입니다.
release_id / version_id발표 상세 조회에는 UUID 형식의 경로 ID와 선택적 UUID 버전 ID를 사용합니다.

알 수 없는 release_id는 404 not_found를 반환합니다. 형식이 잘못되거나 변조되었거나 필터와 맞지 않는 커서는 400 invalid_cursor를 반환합니다. 30분이 지난 커서나 사용할 수 없는 스냅샷은 409 cursor_expired를 반환합니다. 만료된 커서를 빼고 다시 시작하세요.

응답 예시

목록 응답 예시입니다. 상세 조회 작업은 동일한 필드에 version과 observed_at이 추가된 발표 객체 하나를 반환합니다.

200 OK
{
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "revision": 0,
      "country": "USA",
      "series_id": "usa-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York",
      "values": []
    }
  ],
  "next_cursor": null
}
필드규칙
namename은 Producer prices나 Labour force survey처럼 정해진 목록에서 선택한 Narwhal의 표준 영문 이름이며, 날짜는 포함하지 않습니다.
series_idseries_id는 tur-producer-prices와 같이 모든 판에서 공유하는 Narwhal의 영구 시계열 ID입니다. UUID가 아닌 슬러그이므로 /v1/economics/series/* 경로에서는 받지 않습니다. 시계열이 아직 분류되지 않았으면 생략합니다.
topictopic은 시계열이 무엇을 측정하는지 나타내며 consumer_prices, labour_force, gdp, merchandise_trade, policy_rate처럼 국가 간에 일관됩니다. 시계열이 아직 분류되지 않은 경우에는 없으며, 새 주제가 추가될 수 있습니다.
stagestage는 발표에 포함된 해당 기간 수치가 어느 회차인지 나타냅니다: flash, advance, first, second, third, preliminary 또는 final. 한 번만 발표되는 경우에는 표시되지 않습니다.
at / date / between / by날짜를 알 수 없거나 추정 범위에 하한만 있으면 시점 필드를 보내지 않습니다. at은 정확한 발표 시각, date는 시각이 정해지지 않은 발표일, between은 양 끝을 포함하는 예상 날짜 범위 [from, to], by는 가능한 가장 늦은 날짜입니다. by는 기한이며 그날 발표한다는 약속은 아닙니다. 모든 타임스탬프는 UTC이며 timezone은 발표 기관의 IANA 시간대입니다.
period / valuesperiod는 발표 자료의 대상 기간이며 공표 기관이 제공하는 상세 수준을 따릅니다. 2026-09(월), 2026-Q3(분기), 2018-04/2018-06(이동 기간), 2026-09-12(일 또는 주), 2025(연도) 형식입니다. 공표 기관이 기간을 명시하지 않으면 생략됩니다. values는 항상 포함되며 수치가 공표되기 전까지는 비어 있습니다. 아래의 값 설명을 참고하세요.
date_basisdate_basis is indicative when the date comes from a third-party calendar and not from the publisher. An indicative date can still move. It is absent when the publisher or the central bank set the date. The publisher's date always wins over the third-party calendar.
meetingmeeting is set on a central bank's policy meeting and holds the meeting's days from the bank's own calendar. kind is scheduled (the date is on the bank's calendar for the year), unscheduled or extraordinary. starts_on is the first day of a multi-day meeting, when the bank gives it, and ends_on is the last day, the day the decision is announced.
revision / version / observed_atrevision은 발표 세부 정보가 변경될 때마다 증가합니다. 한 번도 수정되지 않았다면 0입니다. GET /v1/economics/calendar/{release_id}는 version_id로 다시 전달할 불변 버전인 version과, Narwhal이 공표 기관의 달력에서 해당 발표를 마지막으로 확인한 시각인 observed_at도 반환합니다.

필드는 값이 있을 때만 포함됩니다. 일부 공표 기관이 발표 일정과 함께 나열하는 연구 기사나 중복 데이터 세트는 포함되지 않습니다.

일정 및 상태 의미

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

발표 시점은 최상위 at, date, between, by 중 한 필드로 표시됩니다. timezone과 제공된 범위의 경계를 보존하세요. by는 기한이며, 그날 발표한다는 약속은 아닙니다. observed_at은 Narwhal이 공표 기관의 달력에서 해당 발표를 마지막으로 확인한 시각입니다.

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

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

Consensus, indicative dates and central bank meetings

Besides the publishers' own schedules, the calendar carries a third-party calendar. It adds a consensus forecast to figures, dates for releases the publishers do not list, and the days of central bank policy meetings. The publisher's date and figure always win over the third-party calendar.

This request returns the Bank Indonesia policy rate decision with a meeting object and a consensus on each rate, and a bank lending release whose date is indicative. Nothing is published yet, so actual is absent.

Policy rate meeting and indicative date
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=IDN&start_date=2026-11-18&end_date=2026-11-18" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "releases": [
    {
      "release_id": "7c9f64b5-bc4c-4875-9757-a5a3be9796dd",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "scheduled",
      "date": "2026-11-18",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "deposit_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5",
          "consensus": "5"
        },
        {
          "measure": "lending_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "6.5",
          "consensus": "6.75"
        },
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5.75",
          "consensus": "6"
        }
      ],
      "meeting": {
        "kind": "scheduled",
        "ends_on": "2026-11-18"
      }
    },
    {
      "release_id": "ff160cc0-f950-4bde-8f98-73dbb6ff6423",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-bank-lending",
      "name": "Bank lending",
      "topic": "money_credit",
      "family": "money",
      "period": "2026-10",
      "status": "scheduled",
      "date_basis": "indicative",
      "at": "2026-11-18T07:30:00Z",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "bank_credit_yoy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "13.26"
        }
      ]
    }
  ],
  "next_cursor": null
}

After a decision, a figure from the third-party calendar shows as provisional until the publisher's own release confirms it. This answer is the Bank Negara Malaysia decision of 5 November 2026.

Provisional figure
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=MYS&start_date=2026-11-05&end_date=2026-11-05" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "releases": [
    {
      "release_id": "007f2565-07af-43df-b778-0abef890689a",
      "revision": 1,
      "country": "MYS",
      "series_id": "mys-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "published",
      "date_basis": "indicative",
      "at": "2026-11-05T07:00:00Z",
      "timezone": "Asia/Kuala_Lumpur",
      "values": [
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "actual": "2.75",
          "previous": "2.75",
          "consensus": "2.75",
          "provisional": true
        }
      ]
    }
  ],
  "next_cursor": null
}

Treat date_basis: indicative and provisional as signs that a date or a figure can still change.

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

The calendar covers 114 countries as of 13 November 2026. Official release schedules from statistical offices and central banks come first. A third-party calendar adds countries and releases that the publishers do not list in a form Narwhal can read. A date that comes only from the third-party calendar carries date_basis indicative. Coverage varies by publisher and economic series; inclusion does not mean every indicator has a schedule. Filter the list request by country and date window to see the releases available in that snapshot.

Countries in the calendar · 114

AGO ALB ARE ARG ARM AUS AUT AZE BEL BGD BGR BHR BIH BLR BRA BWA CAN CHE CHL CHN COL CPV CRI CYP CZE DEU DNK DOM ECU EGY EMU ESP EST FIN FRA GBR GEO GHA GRC GTM HKG HRV HUN IDN IND IRL ISL ISR ITA JAM JOR JPN KAZ KEN KGZ KOR LBN LKA LSO LTU LUX LVA MAC MAR MDA MEX MKD MLT MNE MNG MOZ MUS MWI MYS NAM NGA NLD NOR NZL OMN PAK PER PHL PNG POL PRT PRY PSE ROU RUS RWA SAU SGP SLV SRB SUR SVK SVN SWE SWZ SYC THA TUN TUR TWN UGA UKR URY USA UZB VNM ZAF ZMB ZWE

Countries with a release calendar page · 114

An empty result means no releases are listed for that query in the snapshot. It does not guarantee that the publisher has no upcoming releases. Central bank meeting dates are served in this calendar as meeting. Public holidays, including bank holidays, and exchange closures are separate calendar datasets: see the public holidays reference 및 다음 exchange closures reference (영어).

수치

Each release in the economic release calendar API includes a values array, empty until figures are published. Each value is a figure printed by the publisher: actual for the release's own period and previous for the period before. An actual that comes from a third-party calendar is marked provisional. Narwhal never computes these figures.

발표된 수치 예시
{
  "values": [
    {
      "measure": "producer_price_change_mom",
      "unit": "percent",
      "transformation": "month_over_month",
      "actual": "0",
      "previous": "0.1",
      "previous_revised_from": "0.2"
    }
  ]
}
필드규칙
measuremeasure는 발표 내 수치의 종류를 식별합니다. 예: producer_price_change_mom.
conceptconcept는 수치가 무엇을 측정하는지 나타냅니다(예: gdp, cpi). 따라서 같은 수치는 어느 나라에서나 같은 concept를 가집니다. transformation 및 annualization과 함께 읽으면 같은 기준끼리 비교할 수 있습니다.
noticenotice에는 ECB의 약관처럼 공표 기관이 접근할 때마다 제시하도록 요구하는 출처 이용 약관이 들어 있습니다. 발표 자료와 함께 표시하세요. 해당 약관이 없으면 생략됩니다.
periodperiod는 값의 대상 기간이 발표의 period와 다를 때만 포함됩니다. 예를 들어 계속 실업수당 청구 건수는 해당 발표의 대상 주보다 한 주 앞선 기간을 다룹니다.
unitunit은 percent(값 1.2는 1.2%를 의미), index(2015=100 등의 index_base 포함), thousands, currency, ratio(예: 구인 배율) 또는 balance(백분율이 아닌 포인트 단위의 설문 응답 순차이)입니다.
currency / scalecurrency(ISO 4217 코드)와 scale(units, thousands, millions, hundred_millions 또는 billions)은 unit이 currency일 때만 표시됩니다. 수치는 발행자가 표기한 배율을 따릅니다.
transformationtransformation은 month_over_month, year_over_year, quarter_over_quarter, three_month_on_three_month 또는 change(고용 증감처럼 수준 차이를 천 단위로 나타낸 값)입니다. 수준값인 경우 생략됩니다.
annualized / not_seasonally_adjustedannualized is true when the figure is at an annual rate, as with U.S. GDP growth. not_seasonally_adjusted is true when the figure is not seasonally adjusted. If annualized is absent, the figure is not annualized. If not_seasonally_adjusted is absent, the figure is seasonally adjusted, or, on a figure from a third-party calendar, the source does not say.
actual / previousactual은 해당 발표의 대상 기간 수치이고, previous는 그 이전 기간의 수치입니다. 둘 다 공표 기관이 게재한 수치이며 Narwhal이 계산하지 않습니다. 발표 자료에 명시되지 않은 수치는 생략됩니다. 이후 다음 발표에서는 앞선 actual이 previous로 포함됩니다.
consensusconsensus is the expected figure for the period, from a third-party calendar. It is a forecast and not a published figure. It is absent when no forecast is known, and it can appear on a value whose actual the publisher printed.
provisionalprovisional is true when actual has not been confirmed by the publisher's own release. The figure comes from a third-party calendar and can change when the publisher publishes. It is absent otherwise.
previous_revised_fromprevious_revised_from은 이번 발표에서 previous를 수정한 경우, 처음 공표되었던 이전 수치입니다.
value_statusvalue_status는 actual이 없을 때만 포함됩니다. pending_capture는 예정 시각이 지난 뒤 수치를 수집하기 전까지의 상태이고, unavailable은 해당 수치 없이 발표가 공표되거나 취소된 상태입니다.

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

이 페이지가 도움이 되었나요?