任何人都可引用的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(六种语言的机构名称与网址)、supportingSources、asOf 和 interpolationAllowed。
docs — 本页地址。

仅 /api/live.json 与 /api/snapshot.json 含有的字段

currency — 金额所用货币(KRW)。
values.derived — debtPerCitizen(人均国家债务)、householdDebtPerCitizen(人均家庭债务)、debtToGdpRatio(国家债务/GDP)、fiscalBalance(总收入−总支出)、tradeBalance(出口−进口)。
meta.{指标} — { source, sourceUrl },与来源页面相同的韩文机构名称。

仅 history.json 含有的字段

from · days — 查询区间的起始时刻和天数。
count — 返回的观测点总数;为0表示尚无累积数据。
series — 各指标的观测点数组。synthetic=true 的点是模型插值,而非实测。

单位:金额为各国货币的一个单位(韩元、美元、日元、欧元、人民币),人口以人计,利率、通胀率和失业率为小数(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、t不是ISO 8601格式,或不在2020-01-01..2030-12-31范围内。响应正文附有正确的示例地址(example)和文档地址(docs)。
404 — 不支持的 country 值。正文为 {"error": "Unsupported country"}。
429 — 同一IP在 /api/live.json 上每分钟请求超过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;结果是确定的,缓存一年也不会变。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/

这些数据不是什么

响应中的数值不是实测值,而是在官方季度和年度发布之间按复利插值得到的估算值。需要权威数字时,请查阅各指标的原始来源: 数据来源 · 方法说明.