누구나 인용할 수 있는 JSON

이 사이트가 화면에 보여 주는 부채 추정치를 누구나 프로그램으로 가져갈 수 있도록 공개 JSON 엔드포인트를 둔다. 응답은 CC BY 4.0 라이선스이며, 인용할 때는 "WorldRealDebt"와 함께 응답에 담긴 citeAs 문구를 그대로 쓰면 된다.

API 키·회원가입·요청 헤더가 필요 없다. 모든 엔드포인트는 GET과 OPTIONS만 받는다.

엔드포인트

GET /api/live.json — 한국 시계의 현재 시점 추정치(초기부터 있던 경로). values 아래에 파생 지표(derived)가 함께 온다.
GET /api/snapshot.json?t=<ISO> — 한국 시계의 특정 시점 스냅샷. t를 반드시 지정해야 한다.

국가별 엔드포인트

GET /api/korea/live.json
GET /api/korea/snapshot.json?t=<ISO>
GET /api/korea/history.json?t=<ISO>&days=<n>

live.json — 해당 국가의 현재 시점 추정치. 국가 정의에 등록된 모든 지표와 지표별 출처 메타데이터를 담는다.
snapshot.json — 해당 국가의 특정 시점 스냅샷. 같은 t는 언제 호출해도 같은 응답을 돌려준다.
history.json — 매일 쌓은 관측 스냅샷 시계열. t 이전의 점만 돌려주며, days는 기본 365일·최대 2000일이고 잘못된 값은 기본값이나 상한으로 바뀐다.

country 자리에 들어갈 수 있는 값: korea, china, japan, spain, usa

응답 필드

asOf — 응답이 가리키는 시점(ISO 8601). live는 요청 시각, snapshot은 t 값이다.
baseAsOf — 보간의 출발점이 된 공식 기준일. 국가 엔드포인트에서는 첫 지표의 기준일이다.
country — 국가 엔드포인트에만 있는 국가 코드(korea·china·japan·usa·spain).
source · license — 사이트 주소와 라이선스 표기(CC-BY-4.0).
citeAs — 그대로 붙여 넣을 수 있는 인용 문구. 엔드포인트 주소와 시점이 들어 있다.
method — 보간 공식: value(t) = base × (1+g)^((t−t₀)/1yr).
values — 지표별 추정치. 키는 지표 이름(nationalDebt, householdDebt, gdp …)이다.
meta — 지표별 출처. 국가 엔드포인트는 primarySource(6개 언어 기관명과 URL)·supportingSources·asOf·interpolationAllowed를 준다.
docs — 이 문서의 주소.

/api/live.json·/api/snapshot.json에만 있는 필드

currency — 금액 단위 통화(KRW).
values.derived — debtPerCitizen(1인당 국가채무), householdDebtPerCitizen(1인당 가계부채), debtToGdpRatio(국가채무/GDP), fiscalBalance(총수입−총지출), tradeBalance(수출−수입).
meta.{지표} — { source, sourceUrl } — 출처 페이지와 같은 한국어 기관명.

history.json 전용 필드

from · days — 조회 구간의 시작 시각과 일수.
count — 돌려준 관측점의 총개수. 0이면 아직 쌓인 데이터가 없다.
series — 지표별 관측점 배열. synthetic=true인 점은 실측이 아닌 모델 보간값이다.

단위: 금액은 각 나라 통화의 1단위(원·달러·엔·유로·위안), 인구는 명, 금리·물가·실업률은 소수(0.0275 = 2.75%)다. 값은 반올림하지 않은 부동소수점이므로 표시할 때 직접 자릿수를 정한다.

응답 예시

GET /api/live.json (2026-10-20T00:00:00Z 시점, 일부 생략):

{
  "asOf": "2026-10-20T00:00:00.000Z",
  "baseAsOf": "2026-01-01T00:00:00+09:00",
  "currency": "KRW",
  "source": "https://worldrealdebt.com",
  "license": "CC-BY-4.0",
  "citeAs": "Korea Debt Clock (https://worldrealdebt.com/api/live.json), accessed 2026-10-20T00:00:00.000Z",
  "method": "compound interpolation: value(t) = base × (1+g)^((t-t₀)/1yr)",
  "values": {
    "nationalDebt": 1392428189250859.8,
    "gdp": 2770569555899763.5,
    "population": 51549209.89518132,
    "householdDebt": 2028123204201555.8,
    "interestRate": 0.0275,
    "exchangeRate": 1546,
    "derived": {
      "debtPerCitizen": 27011630.092530675,
      "householdDebtPerCitizen": 39343439.178320736,
      "debtToGdpRatio": 0.5025783187019314,
      "fiscalBalance": -57187411253740.5,
      "tradeBalance": 117679974849796.38
    }
  },
  "meta": {
    "nationalDebt": {
      "source": "기획재정부 국가채무 잠정",
      "sourceUrl": "https://www.moef.go.kr/"
    },
    "householdDebt": {
      "source": "한국은행 가계신용 통계",
      "sourceUrl": "https://ecos.bok.or.kr/"
    }
  },
  "docs": "https://worldrealdebt.com/api-docs/"
}

GET /api/korea/live.json — 시점, 값 계열 6개와 meta 첫 항목만 남김. 실제 응답 빌더로 생성:

{
  "country": "korea",
  "asOf": "2026-10-20T00:00:00.000Z",
  "baseAsOf": "2026-01-01T00:00:00+09:00",
  "source": "https://worldrealdebt.com",
  "license": "CC-BY-4.0",
  "citeAs": "WorldRealDebt, South Korea debt data (https://worldrealdebt.com/api/korea/live.json), accessed 2026-10-20T00:00:00.000Z",
  "method": "compound interpolation: value(t) = base × (1+g)^((t-t₀)/1yr)",
  "values": {
    "nationalDebt": 1392428189250859.8,
    "householdDebt": 2028123204201555.8,
    "mortgageDebt": 1201188973927010.2,
    "creditCardDebt": 130449280606744.97,
    "gdp": 2770569555899763.5,
    "population": 51549209.89518132,
    "…": "…"
  },
  "meta": {
    "nationalDebt": {
      "primarySource": {
        "name": {
          "en": "MoEF National Debt (provisional)",
          "ko": "기획재정부 국가채무 잠정",
          "ja": "企画財政部 国家債務 暫定",
          "fr": "Ministère de l’Économie et des Finances — dette publique provisoire",
          "zh": "韩国企划财政部 国家债务暂定值",
          "es": "Ministerio de Economía y Hacienda — deuda pública (provisional)"
        },
        "url": "https://www.moef.go.kr/"
      },
      "supportingSources": [
        {
          "name": "IMF Global Debt Database",
          "url": "https://www.imf.org/external/datamapper/datasets/GDD"
        }
      ],
      "asOf": "2026-01-01T00:00:00+09:00",
      "interpolationAllowed": true
    }
  },
  "docs": "https://worldrealdebt.com/korea/api-docs/"
}

오류 응답

400 — t가 없거나 ISO 8601이 아니거나 2020-01-01..2030-12-31 밖일 때. 본문에 올바른 예시 주소(example)와 문서 주소(docs)가 담긴다.
404 — 지원하지 않는 country 값. 본문은 {"error": "Unsupported country"}.
429 — /api/live.json에서 같은 IP가 1분에 60회를 넘었을 때. Retry-After: 60 헤더를 준다.

호출 한도·CORS·캐시

/api/live.json은 IP당 분당 60회로 제한한다. 카운터 저장소(Valkey)가 응답하지 않으면 제한을 건너뛰고 응답을 우선한다.
live 계열은 Cache-Control: public, max-age=30, s-maxage=30 — 30초 안의 재요청은 캐시된 값을 받는다.
snapshot 계열은 max-age=31536000, immutable — 결정론적이라 1년간 캐시해도 같다. history도 데이터가 있으면 같은 정책이고, 비어 있으면 60초만 캐시한다.
Access-Control-Allow-Origin: * — 어느 웹사이트의 브라우저 코드에서도 바로 호출할 수 있다.

인용 문구

응답의 citeAs를 쓰거나, 아래 형식으로 원출처를 함께 적는다:

South Korea Debt Clock (https://worldrealdebt.com/api/korea/live.json), accessed YYYY-MM-DD.
Underlying sources: see meta.*.primarySource in the response, or https://worldrealdebt.com/sources/

이 데이터가 아닌 것

응답 값은 측정치가 아니라 공식 분기·연간 발표 사이를 복리 보간한 추정치다. 공식 수치가 필요하면 각 지표의 원출처를 확인한다: 데이터 출처 · 방법론.