誰でも引用できる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 — そのまま貼り付けられる引用文。エンドポイントのURLと時点を含む。
• 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の範囲外のとき。本文に正しい例のURL(example)と文書のURL(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/

このデータが意味しないこと

応答の値は測定値ではなく、公式の四半期・年次発表の間を複利で補間した推定値である。公式の数値が必要なら、各指標の原出典を確認してほしい: データの出典 · 方法論.