Un JSON que chacun peut citer

Des endpoints JSON publics permettent à chacun de reprendre dans son propre code les estimations de dette affichées sur le site. Les réponses sont publiées sous licence CC BY 4.0 ; pour les citer, créditez « WorldRealDebt » et reprenez la chaîne citeAs fournie dans chaque réponse.

Aucune clé d’API, inscription ni en-tête particulier n’est nécessaire. Tous les endpoints n’acceptent que GET et OPTIONS.

Endpoints

GET /api/live.json — Estimation courante de l’horloge coréenne (le chemin d’origine). Les indicateurs dérivés figurent sous values.derived.
GET /api/snapshot.json?t=<ISO> — Instantané de l’horloge coréenne à un instant donné. t est obligatoire.

Endpoints par pays

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

live.json — Estimation courante pour le pays : tous les indicateurs enregistrés dans la définition du pays, avec les métadonnées de source de chacun.
snapshot.json — Instantané du pays à un instant donné. Un même t renvoie la même réponse à chaque appel.
history.json — Série chronologique des instantanés observés chaque jour. Seuls les points antérieurs à t sont renvoyés ; days vaut 365 par défaut, 2000 au maximum, et une valeur invalide revient à la valeur par défaut ou au plafond.

Valeurs possibles pour country: korea, china, japan, spain, usa

Champs de la réponse

asOf — L’instant décrit par la réponse (ISO 8601) : l’heure de la requête pour live, la valeur de t pour snapshot.
baseAsOf — La date de référence officielle d’où part l’interpolation ; pour les endpoints par pays, celle du premier indicateur.
country — Code pays, uniquement sur les endpoints par pays (korea, china, japan, usa, spain).
source · license — Adresse du site et mention de licence (CC-BY-4.0).
citeAs — Une citation prête à coller, avec l’URL de l’endpoint et l’instant.
method — La formule d’interpolation : value(t) = base × (1+g)^((t−t₀)/1yr).
values — Les estimations par indicateur, indexées par nom (nationalDebt, householdDebt, gdp…).
meta — Les sources par indicateur. Les endpoints par pays fournissent primarySource (nom de l’institution en six langues et URL), supportingSources, asOf et interpolationAllowed.
docs — L’adresse de cette page.

Champs propres à /api/live.json et /api/snapshot.json

currency — Devise des montants (KRW).
values.derived — debtPerCitizen (dette nationale par habitant), householdDebtPerCitizen (dette des ménages par habitant), debtToGdpRatio (dette nationale / PIB), fiscalBalance (recettes − dépenses) et tradeBalance (exportations − importations).
meta.{indicateur} — { source, sourceUrl } : le même libellé d’institution en coréen que sur la page des sources.

Champs propres à history.json

from · days — Début de la fenêtre demandée et sa durée en jours.
count — Nombre total de points renvoyés ; 0 signifie qu’aucune donnée n’a encore été accumulée.
series — Tableaux d’observations par indicateur. Les points marqués synthetic=true sont des interpolations du modèle, pas des observations.

Unités : les montants sont exprimés en unités de la monnaie nationale (won, dollar, yen, euro, yuan), la population en personnes, et les taux — intérêt, inflation, chômage — en fraction (0,0275 = 2,75 %). Les valeurs sont des décimaux non arrondis : choisissez vous-même la précision à l’affichage.

Exemples de réponse

GET /api/live.json à 2026-10-20T00:00:00Z (abrégée) :

{
  "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 — au même instant, en ne gardant que six séries de valeurs et la première entrée de meta. Générée avec le constructeur de réponse de la route elle-même :

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

Réponses d’erreur

400 — t est absent, n’est pas au format ISO 8601 ou sort de 2020-01-01..2030-12-31. Le corps contient une URL d’exemple correcte (example) et cette page (docs).
404 — Valeur de country non prise en charge. Corps : {"error": "Unsupported country"}.
429 — Plus de 60 requêtes par minute depuis une même IP sur /api/live.json. Accompagnée de l’en-tête Retry-After: 60.

Limites · CORS · cache

/api/live.json est limité à 60 requêtes par minute et par IP. Si le stockage du compteur (Valkey) ne répond pas, la limite est ignorée pour privilégier la réponse.
Les endpoints live envoient Cache-Control: public, max-age=30, s-maxage=30 : les requêtes répétées dans les 30 secondes reçoivent la valeur en cache.
Les endpoints snapshot envoient max-age=31536000, immutable : ils sont déterministes, un an de cache ne change donc rien. history suit la même règle lorsqu’il contient des données et ne met en cache que 60 secondes lorsqu’il est vide.
Access-Control-Allow-Origin: * : appelables directement depuis le code navigateur de n’importe quel site.

Comment citer

Reprenez la chaîne citeAs de la réponse, ou cette forme avec les sources primaires :

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/

Ce que ces données ne sont pas

Les valeurs renvoyées ne sont pas des mesures, mais des estimations obtenues par interpolation composée entre les publications officielles trimestrielles et annuelles. Pour les chiffres faisant foi, reportez-vous à la source primaire de chaque indicateur : Sources des données · Méthodologie.