전체 문서 탐색

경상수지 과거 데이터 API

한 국가의 분기별 경상수지를 미국 달러로 오래된 순으로 조회합니다.

economics_get_current_account_history —REST와 다음 economics_get_current_account_history MCP 도구입니다. 둘 다 같은 데이터 형식을 반환하며 같은 크레딧을 사용합니다.

엔드포인트 및 요청

REST 엔드포인트
GET /v1/economics/{country}/current-account/observations
요청 예시
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/IDN/current-account/observations?start=2025-Q1&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

매개변수

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

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

응답

응답 예시
{
  "source": {
    "publisher": "Country authorities; National Summary Data Pages; European Central Bank; IMF Staff Estimates",
    "distributor": "International Monetary Fund"
  },
  "accounting_standard": "BPM6",
  "time_basis": "period_flow",
  "country": "IDN",
  "series_id": "b025aa04-14db-4649-87b8-359c20069196",
  "unit": "currency",
  "currency": "USD",
  "observations": [
    {
      "period": "2025-Q1",
      "value": "-68155035.6104999"
    },
    {
      "period": "2025-Q2",
      "value": "-2889388710.26253"
    }
  ],
  "next_cursor": "eyJhZnRlciI6IjIwMjUtUTIi…"
}

이력 예제는 limit=2를 요청하므로 두 행이 있습니다. 여기서는 next_cursor를 줄여 표시했습니다. 실제 값은 더 긴 불투명 문자열입니다.

필드유형필수의미
source객체예수치를 발행한 기관입니다. publisher는 IMF 시계열 메타데이터에 명시된 원래 발행 기관이고, distributor는 Narwhal이 읽어 오는 IMF입니다. 시계열당 전체 이력에 하나의 출처만 있습니다. released_on은 없습니다.
accounting_standard문자열예수치가 따르는 국제수지 매뉴얼이며, 예를 들어 BPM6입니다.
time_basis문자열예항상 period_flow: 분기 동안의 순 흐름이며 잔액이 아닙니다.
country문자열예요청된 대문자 ISO alpha-3 국가 코드입니다.
series_id문자열예수치가 나온 시계열입니다. 같은 시계열을 다시 읽으려면 series_id로 전달하세요.
unit문자열예Always currency.
currencyISO 4217 문자열예Always USD.
observations배열예기간당 하나씩 오래된 순서의 관측값입니다. 한 페이지에 limit보다 적은 관측값이 있을 수 있습니다. next_cursor가 null이 될 때까지 따라가세요.
observations[].period문자열예관측값이 나타내는 공식 월, 분기 또는 연도입니다.
observations[].value십진수 문자열예해당 분기의 순 경상수지이며 미국 달러 기준입니다. 음수 값은 적자입니다.
observations[].status문자열아니요발행 기관이 표시한 수치에만 포함됩니다: estimated, break_in_series, definition_differs, break_in_series_and_definition_differs. 그렇지 않으면 생략됩니다.
observations[].release_status문자열아니요발행 기관이 수치를 잠정치로 표시한 경우 preliminary입니다. 그렇지 않으면 생략됩니다.
next_cursor문자열 또는 null예다음 페이지를 읽으려면 이 값을 변경하지 말고 cursor로 전달하세요. 마지막 페이지에서는 null입니다.

API 오류 코드와 크레딧

  • 400 invalid_query: A query parameter is unknown or repeated, country is not three uppercase letters, series_id is not a UUID, start or end is not a quarter in YYYY-QN format, start and end differ in format or start is after end, or limit is outside 1 to 1000. version_id, version and as_of are not accepted on this route.
  • 400 invalid_cursor: 커서의 형식이 잘못되었거나 다른 필터용으로 발급되었습니다.
  • 409 snapshot_unavailable: 커서가 24시간이 넘어 만료되었습니다. cursor 없이 다시 시작하세요.
  • 401 invalid_api_key: Bearer 키가 누락되었거나 거부되었습니다.
  • 402 insufficient_credits: 잔액이 호출 비용에 부족합니다.
  • 404 series_not_found: 해당 국가가 이 페이지의 지원 국가 목록에 없거나, series_id가 그 국가의 시계열이 아니거나, 범위에 관측값이 없습니다. 목록에 없는 국가에는 해당 지표군을 이용할 수 없다는 상세 설명이 반환됩니다. 404는 요금이 부과되지 않습니다.
  • 429 rate_limit_exceeded: 네트워크 또는 계정의 단기 구간 한도에 도달했습니다. Retry-After 이후에 다시 시도하세요.
  • 503 economics_unavailable: Narwhal이 저장된 시계열을 안전하게 제공할 수 없습니다.

Only a successful data response costs credit. 확인 모든 오류, 헤더 및 재시도 규칙.

최신성

이 경로는 Narwhal이 현재 저장한 시계열을 오래된 순으로 반환합니다. start가 없으면 저장된 가장 오래된 기간부터 시작하므로, 최근 기간을 읽으려면 start를 전달하세요. as_of나 version을 받지 않으므로 이전 시점의 데이터는 읽을 수 없습니다. Narwhal은 누락된 관측값을 채우지 않고 생략합니다.

읽기 출처 확인, 검증, 발표 데이터 저장 및 확인 실패 시 처리 방식.

현재 공개 베타 데이터 범위

9 국가

ARG, CHN, IDN, KOR, MEX, SLV, THA, UKR, URY

분기별, 미국 달러 기준입니다. 수지는 상품, 서비스, 소득, 이전의 순액이며 음수 값은 적자입니다. 국제통화기금(IMF)이 시계열을 배포하며 source.publisher가 원래 발행 기관을 나타냅니다. 기간은 YYYY-QN 형식의 분기입니다. 다른 국가는 404 not_found를 반환하며 요금이 부과되지 않습니다.

일일 환율을 제공하는 API: 환율 API.

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

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