WorldRealDebt.

Un JSON que cualquiera puede citar

Los endpoints JSON públicos permiten que cualquiera lleve a su propio código las estimaciones de deuda que muestra este sitio. Las respuestas se publican con licencia CC BY 4.0; al citarlas, mencione «WorldRealDebt» y use la cadena citeAs incluida en cada respuesta.

No hace falta clave de API, registro ni cabeceras especiales. Todos los endpoints aceptan solo GET y OPTIONS.

Endpoints

  • GET /api/live.json — Estimación actual del reloj de Corea (la ruta original). Los indicadores derivados llegan en values.derived.
  • GET /api/snapshot.json?t=<ISO> — Instantánea del reloj de Corea en un momento dado. t es obligatorio.

Endpoints por país

GET /api/korea/live.json
GET /api/korea/snapshot.json?t=<ISO>
GET /api/korea/history.json?t=<ISO>&days=<n>
  • live.json — Estimación actual del país: todos los indicadores registrados en la definición del país, con los metadatos de fuente de cada uno.
  • snapshot.json — Instantánea del país en un momento dado. El mismo t devuelve la misma respuesta cada vez que se llama.
  • history.json — Serie temporal de instantáneas observadas a diario. Solo devuelve puntos hasta t; days vale 365 por defecto con un máximo de 2000, y los valores no válidos pasan al valor por defecto o al tope.

Valores válidos para country: korea, china, japan, spain, usa

Campos de la respuesta

  • asOf — El momento que describe la respuesta (ISO 8601): la hora de la petición en live, el valor de t en snapshot.
  • baseAsOf — La fecha oficial de referencia desde la que parte la interpolación; en los endpoints por país, la del primer indicador.
  • country — Código de país, solo en los endpoints por país (korea, china, japan, usa, spain).
  • source · license — Dirección del sitio y etiqueta de licencia (CC-BY-4.0).
  • citeAs — Una cita lista para pegar, con la URL del endpoint y el momento.
  • method — La fórmula de interpolación: value(t) = base × (1+g)^((t−t₀)/1yr).
  • values — Estimaciones por indicador, con el nombre del indicador como clave (nationalDebt, householdDebt, gdp…).
  • meta — Fuentes por indicador. Los endpoints por país dan primarySource (nombre de la institución en seis idiomas y URL), supportingSources, asOf e interpolationAllowed.
  • docs — La dirección de esta página.

Campos exclusivos de /api/live.json y /api/snapshot.json

  • currency — Moneda de los importes (KRW).
  • values.derived — debtPerCitizen (deuda nacional por habitante), householdDebtPerCitizen (deuda de los hogares por habitante), debtToGdpRatio (deuda nacional / PIB), fiscalBalance (ingresos − gastos) y tradeBalance (exportaciones − importaciones).
  • meta.{indicador} — { source, sourceUrl }: el mismo nombre de institución en coreano que en la página de fuentes.

Campos exclusivos de history.json

  • from · days — Inicio de la ventana consultada y su duración en días.
  • count — Número total de puntos devueltos; 0 significa que aún no se han acumulado datos.
  • series — Listas de observaciones por indicador. Los puntos marcados synthetic=true son interpolaciones del modelo, no observaciones.

Unidades: los importes van en unidades de la moneda nacional (won, dólar, yen, euro, yuan), la población en personas y los tipos —interés, inflación, paro— en fracción (0,0275 = 2,75 %). Los valores son decimales sin redondear, así que elija usted la precisión al mostrarlos.

Ejemplos de respuesta

GET /api/live.json a las 2026-10-20T00:00:00Z (recortada):

{
  "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 — en el mismo momento, conservando seis series de valores y la primera entrada de meta. Generada con el mismo constructor de respuestas que usa la ruta:

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

Respuestas de error

  • 400 — Falta t, no es ISO 8601 o está fuera de 2020-01-01..2030-12-31. El cuerpo incluye una URL de ejemplo correcta (example) y esta página (docs).
  • 404 — Valor de country no admitido. Cuerpo: {"error": "Unsupported country"}.
  • 429 — Más de 60 peticiones por minuto desde una misma IP en /api/live.json. Llega con la cabecera Retry-After: 60.

Límites · CORS · caché

  • /api/live.json está limitado a 60 peticiones por minuto e IP. Si el almacén del contador (Valkey) no responde, se omite el límite para priorizar la respuesta.
  • Los endpoints live envían Cache-Control: public, max-age=30, s-maxage=30: las peticiones repetidas en 30 segundos reciben el valor en caché.
  • Los endpoints snapshot envían max-age=31536000, immutable: son deterministas, así que un año de caché no cambia nada. history sigue la misma política cuando tiene datos y solo guarda 60 segundos cuando está vacío.
  • Access-Control-Allow-Origin: *: se pueden llamar directamente desde el código del navegador de cualquier sitio web.

Cómo citar

Use la cadena citeAs de la respuesta o esta forma con las fuentes originales:

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/

Lo que estos datos no son

Los valores de la respuesta no son mediciones, sino estimaciones obtenidas por interpolación compuesta entre las publicaciones oficiales trimestrales y anuales. Para las cifras oficiales, acuda a la fuente primaria de cada indicador: Fuentes de datos · Metodología.