소비자물가지수 과거 데이터 API

특정 국가의 현재 승인된 소비자물가지수 시계열을 조회합니다.

economics_get_cpi_history —REST와 다음 economics_get_cpi_history MCP 도구를 통해 이용할 수 있습니다. 두 방식은 동일한 데이터 구조를 반환하고 동일한 월간 할당량을 소비합니다.

엔드포인트 및 요청

REST 엔드포인트

GET /v1/economics/{country}/cpi/observations

요청 예시

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

MCP에서 사용하는 도구: economics_get_cpi_history —아래의 해당 인수로 호출하세요.

매개변수

이 작업에서 허용되는 기간 형식: YYYY-MM.

이름	필수	유형	의미
`country`	예	경로 · ISO alpha-3	지원되는 대문자 국가 코드 1개입니다. 이 작업의 범위 목록을 확인하세요.
`start`	아니요	쿼리 · YYYY-MM	첫 관측 기간이며 해당 기간을 포함합니다. Free와 Basic에서는 시작 기간이 요금제 범위보다 이전이면 범위 내 첫 기간으로 옮깁니다. 이 경우 응답에 start가 포함됩니다.
`end`	아니요	쿼리 · YYYY-MM	조회 범위의 마지막 관측 기간이며, 해당 기간도 포함합니다.
`limit`	아니요	쿼리 · 정수, 1~1000	반환할 최대 기간 수입니다. 기본값은 100입니다. 한 페이지에 더 적은 기간이 포함될 수 있으므로 next_cursor를 따라가세요.
`cursor`	아니요	쿼리 · 불투명 문자열	이전 페이지의 next_cursor입니다.

응답

응답 예시

{
  "country": "USA",
  "index_base": "1982-84=100",
  "as_of": "2026-08-12T00:00:00Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "333.918"
    }
  ],
  "next_cursor": null
}

필드	유형	필수	의미
`country`	문자열	예	요청한 대문자 ISO alpha-3 국가 코드입니다. 관측값마다가 아니라 페이지당 한 번 반환합니다.
`start`	문자열	아니요	요금제에 따라 요청한 start가 더 뒤의 기간으로 이동한 경우에만 포함됩니다. 그보다 이전 기간은 반환하지 않습니다.
`as_of`	RFC 3339 타임스탬프	아니요	이 페이지의 가장 최근 관측값을 소스가 마지막으로 갱신한 시각입니다. UTC 기준이며 소수점 이하 초는 없습니다.
`source`	객체	아니요	유통업체를 통해 받은 통계의 출처 정보입니다. 최신 값 조회 작업을 참조하세요.
`index_base`	문자열	예	지수의 기준 기간과 기준값입니다. 예: 1982-84=100. 한 페이지에 서로 다른 두 기준이 섞이지 않습니다.
`observations`	배열	예	채택된 관측값을 오래된 순서로 기간당 하나씩 반환합니다. 소스에 없는 값은 생략하며 채워 넣지 않습니다. 한 페이지의 관측값 수가 limit보다 적을 수 있으므로 next_cursor가 null이 될 때까지 따라가세요.
`observations[].period`	문자열	예	관측값이 나타내는 공식 월 또는 분기입니다.
`observations[].value`	십진수 문자열	예	이진 부동소수점 변환을 거치지 않은 채택된 지수 수준입니다.
`next_cursor`	문자열 또는 null	예	다음 페이지를 읽으려면 이 값을 변경하지 않고 cursor로 전달하세요. 마지막 페이지에서는 null입니다.

오류 및 할당량

400 invalid_query — 국가, 기간 또는 필터 형식이 잘못되었습니다.
400 invalid_cursor — 커서 형식이 잘못되었거나 다른 필터 또는 작업에 대해 발급되었습니다.
401 invalid_api_key — Bearer 키가 누락되었거나 거부되었습니다.
403 plan_upgrade_required — 요청 기간 또는 범위가 요금제의 과거 데이터 범위(Free 12개월, Basic 5년)보다 이전에 끝납니다.
404 series_not_found — 요청과 일치하는 승인 관측값이 없습니다.
409 cursor_expired 페이지네이션 커서가 너무 오래되었거나 대상 데이터가 변경되었습니다. 커서 없이 다시 시작하세요.
429 rate_limit_exceeded —네트워크 또는 계정의 단기 구간 한도에 도달했습니다. 재시도 전 대기 시간은 다음 헤더를 따르세요: Retry-After.
429 quota_exhausted — 계정이 월간 허용량에 도달했습니다.
503 economics_unavailable — Narwhal이 승인 발표를 안전하게 제공할 수 없습니다.

성공한 데이터 응답만 할당량을 소비합니다. 참고 항목: 모든 오류, 헤더 및 재시도 규칙.

현재 공개 베타 데이터 범위

34 국가

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, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA

사용 가능한 공식 과거 데이터는 이 작업의 국가 범위를 따릅니다. 최초 제공 기간은 출처에 따라 다릅니다.

인도네시아 및 지역 경제 데이터 경로는 공개되지 않습니다. 일일 환율을 제공하는 API: 환율 API.

다음으로 돌아가기 모든 경제 데이터 작업.

엔드포인트 및 요청

매개변수

응답

오류 및 할당량

최신성

현재 공개 베타 데이터 범위