JSON anyone can cite

Public JSON endpoints let anyone take the debt estimates shown on this site into their own code. Responses are licensed under CC BY 4.0; when you cite them, credit “WorldRealDebt” and use the citeAs string included in each response.

No API key, sign-up or request headers are required. Every endpoint accepts only GET and OPTIONS.

Endpoints

• GET /api/live.json — Current estimate for the Korea clock (the original path). Derived indicators arrive under values.derived.
• GET /api/snapshot.json?t=<ISO> — Point-in-time snapshot for the Korea clock. t is required.

Primary endpoint — per country

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

• live.json — Current estimate for the country: every metric registered in the country definition, with per-metric source metadata.
• snapshot.json — Point-in-time snapshot for the country. The same t returns the same response whenever you call it.
• history.json — Daily observed snapshots as a time series. Only points up to t are returned; days defaults to 365 with a maximum of 2000, and invalid values fall back to the default or the cap.

Valid values for country: korea, china, japan, spain, usa

Response fields

• asOf — The moment the response describes (ISO 8601): the request time for live, the t value for snapshot.
• baseAsOf — The official reference date the interpolation starts from; on country endpoints, the first metric’s reference date.
• country — Country code, on country endpoints only (korea, china, japan, usa, spain).
• source · license — Site address and licence tag (CC-BY-4.0).
• citeAs — A ready-to-paste citation containing the endpoint URL and the moment.
• method — The interpolation formula: value(t) = base × (1+g)^((t−t₀)/1yr).
• values — Estimates by metric, keyed by metric name (nationalDebt, householdDebt, gdp …).
• meta — Sources by metric. Country endpoints give primarySource (institution name in six languages, plus URL), supportingSources, asOf and interpolationAllowed.
• docs — The address of this page.

Fields only on /api/live.json and /api/snapshot.json

• currency — Currency of monetary values (KRW).
• values.derived — debtPerCitizen, householdDebtPerCitizen, debtToGdpRatio (national debt / GDP), fiscalBalance (revenue − spending) and tradeBalance (exports − imports).
• meta.{metric} — { source, sourceUrl } — the same Korean institution label as on the sources page.

Fields only on history.json

• from · days — Start of the requested window and its length in days.
• count — Total number of points returned; 0 means no data has accumulated yet.
• series — Arrays of observations by metric. Points flagged synthetic=true are model interpolations, not observations.

Units: money is in single units of the national currency (won, dollar, yen, euro, yuan), population in persons, and rates such as interest, inflation and unemployment as fractions (0.0275 = 2.75%). Values are unrounded floats, so choose your own precision when displaying them.

Sample responses

GET /api/live.json at 2026-10-20T00:00:00Z (trimmed):

{
  "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 — at the same moment, keeping six value series and the first meta entry. Generated with the route’s own payload builder:

{
  "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/"
}

Error responses

• 400 — t is missing, not ISO 8601, or outside 2020-01-01..2030-12-31. The body includes a correct example URL (example) and this page (docs).
• 404 — Unsupported country value. Body: {"error": "Unsupported country"}.
• 429 — More than 60 requests per minute from one IP on /api/live.json. Comes with a Retry-After: 60 header.

Rate limits · CORS · caching

• /api/live.json is limited to 60 requests per minute per IP. If the counter store (Valkey) is unavailable, the limit is skipped in favour of answering.
• Live endpoints send Cache-Control: public, max-age=30, s-maxage=30 — repeat requests within 30 seconds get the cached value.
• Snapshot endpoints send max-age=31536000, immutable — they are deterministic, so a year of caching changes nothing. history follows the same policy when it has data and caches for only 60 seconds when empty.
• Access-Control-Allow-Origin: * — callable straight from browser code on any website.

Cite as

Use the response’s citeAs string, or this form with the underlying sources:

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/

What this is not

Response values are not measurements but estimates obtained by compound interpolation between official quarterly and annual releases. For authoritative figures, go to each metric’s primary source: Data sources · Methodology.