경제 데이터 API 레퍼런스

국가 및 지표별 범위가 표시된 최신 발표와 과거 관측값입니다.

7개 경로는 최신 채택된 공식 발표를 반환합니다. 이에 대응하는 7개 /observations 경로는 현재 승인 시계열을 반환합니다. REST와 MCP는 동일한 스키마와 월간 할당량을 사용합니다.

기본 URL 및 매개변수

REST 기본 경로

https://api.narwhalapi.com/v1/economics/{country}

country 지원되는 대문자 ISO alpha-3 코드입니다.
period 매개변수는 선택 사항입니다. 최신 발표를 조회하려면 생략하고, 특정 기간을 조회하려면 해당 작업의 월·분기·연도 형식으로 지정하세요.
/v1/economics/{country}/cpi 같은 코어 경제 데이터 엔드포인트와 해당 MCP 도구는 주요 지표의 잠정적인 최초 추정치를 반환할 수 있으며, 응답에는 잠정치임이 표시되지 않고, 출처에서 확정치를 발표하면 Narwhal API가 이 값을 대체합니다.
모든 요청에는 Bearer 헤더가 필요합니다. 설명 문서: 인증.

알려진 기간 하나 요청

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/cpi?period=2026-07" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

국가

36 국가

AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA

범위는 작업과 국가에 따라 다릅니다. 각 작업에 지원 국가가 표시됩니다.

최근 발표

정확한 매개변수, 허용되는 기간 형식, 응답 필드, 예시, 오류, 최신성 및 현재 제한을 확인하려면 작업 페이지를 여세요.

작업	REST 경로	기간
소비자물가지수	`/v1/economics/{country}/cpi`	`YYYY-MM`
인플레이션	`/v1/economics/{country}/inflation`	`YYYY-MM`
실업률	`/v1/economics/{country}/unemployment`	`YYYY, YYYY-MM, or YYYY-QN`
경제활동참가율	`/v1/economics/{country}/labour-force-participation`	`YYYY, YYYY-MM, or YYYY-QN`
국내총생산	`/v1/economics/{country}/gdp`	`YYYY-QN`
GDP 성장률	`/v1/economics/{country}/gdp-growth`	`YYYY-QN`
상품 무역	`/v1/economics/{country}/trade`	`YYYY or YYYY-MM`

과거 관측값

과거 데이터 경로에서 허용하는 매개변수: start, end, limit, 및 cursor. 결과는 오래된 순으로 정렬되며, 과거의 모든 발표 버전이 아니라 현재 승인된 시계열을 나타냅니다.

작업	REST 경로	기간
소비자물가지수 과거 데이터	`/v1/economics/{country}/cpi/observations`	`YYYY-MM`
인플레이션 과거 데이터	`/v1/economics/{country}/inflation/observations`	`YYYY-MM`
실업률 과거 데이터	`/v1/economics/{country}/unemployment/observations`	`YYYY, YYYY-MM, or YYYY-QN`
경제활동참가율 과거 데이터	`/v1/economics/{country}/labour-force-participation/observations`	`YYYY, YYYY-MM, or YYYY-QN`
국내총생산 과거 데이터	`/v1/economics/{country}/gdp/observations`	`YYYY-QN`
GDP 성장률 과거 데이터	`/v1/economics/{country}/gdp-growth/observations`	`YYYY-QN`
상품 무역 과거 데이터	`/v1/economics/{country}/trade/observations`	`YYYY-MM`

필드 규칙

필드 또는 규칙	의미
`country`	요청된 ISO alpha-3 국가 코드입니다.
`period`	응답이 나타내는 정확한 공식 월, 분기 또는 연도입니다.
`released_on`	Narwhal 조회 시각이 아닌 공식 발표일입니다.
십진수 문자열	정확한 십진 표현을 보존하기 위해 숫자형 경제 값은 문자열로 반환됩니다.
단위 및 기준	퍼센트 필드는 이름으로 단위를 나타냅니다. 통화와 지수 기준도 명시합니다. 시계열이 계절 조정되지 않았거나 연율로 환산된 경우에만 플래그가 표시됩니다.
누락된 발표	Narwhal은 누락값을 만들어내거나 이전 값으로 채우거나 0으로 변환하지 않고, 제공을 차단하고 오류를 반환합니다.

ID로 시계열 이력 조회

GET /v1/economics/series/{series_id}/observations는 ID로 지정한 시계열 하나의 이력을 반환합니다. MCP 도구: economics_read_series_observations. ID는 UUID입니다. 경제 발표 캘린더의 series_id 값인 usa-new-home-sales 같은 슬러그는 허용되지 않으며 400 invalid_query를 반환합니다. 호주 월간 CPI 지표(예: 284aaefe-7919-4728-bc15-50879ba77211)와 뉴질랜드 분기 CPI, 두 시계열을 제공합니다.

선택 항목인 start와 end는 YYYY, YYYY-MM, YYYY-MM-DD, YYYY-QN을 받습니다. limit은 1–1000(기본값 100)입니다. 다음 페이지는 next_cursor를 cursor로 전달하세요. Free와 Basic은 요금제의 과거 데이터 범위만 읽을 수 있습니다. 더 이전 범위는 403 plan_upgrade_required를 반환합니다. 알 수 없는 시계열은 404 not_found를 반환합니다.

응답 예시

{
  "country": "AUS",
  "series_id": "284aaefe-7919-4728-bc15-50879ba77211",
  "unit": "percent",
  "observations": [
    {
      "period": "2018-09",
      "value": "2",
      "released_on": "2025-10-29"
    },
    {
      "period": "2018-10",
      "value": "2.3",
      "released_on": "2025-10-29"
    }
  ],
  "next_cursor": null
}

country, series_id, unit, observations, next_cursor는 항상 있습니다. 마지막 페이지의 next_cursor는 null입니다. 각 관측값에는 period, value, released_on이 있습니다. currency와 source는 해당되는 경우에만 나타납니다.

OpenAPI 및 검색

현재 공개 베타 제한

미국, 영국, 독일, 일본, 캐나다 국채 수익률 곡선입니다. REST와 MCP로 특정 기준일 데이터나 페이지별 이력을 조회하세요.

인도네시아 및 지역별 경로는 Economics API 공개 베타에 포함되지 않습니다.

확인 오류 및 할당량 —시계열이 없거나 서비스를 이용할 수 없을 때의 동작을 확인하세요.