API ドキュメント

使い方の流れ

1. 起動したら、REST で今の状態を取ります（GET /v2/earthquakes/latest、GET /v2/tsunami）。
2. WebSocket か SSE につなぎ、届いた earthquake / tsunami メッセージで手元の状態を置き換えます。
3. 切れたら、最後に受け取った seq を付けて再接続します。取りこぼした分が先に届きます。
4. resync が届いたら、取りこぼしを埋められなかったということなので、手順1からやり直します。

共通の約束ごと

この先、キーが増えることがあります。知らないキーは無視するように作ってください。キーをなくしたり意味を変えたりするのは、/v3 にするときだけです。

リアルタイム配信

WebSocket と SSE は同じメッセージを送ります。WebSocket はつないだあとに条件を変えられるのでサーバーのプログラムに、SSE はブラウザの EventSource で数行で使えます。

メッセージ

// 地震の状態が変わった（data は Earthquake 全体）
{ "type": "earthquake", "seq": 1042, "sentAt": "…", "reportId": "…", "data": { … } }

// 津波の状態が変わった（data は Tsunami 全体）
{ "type": "tsunami", "seq": 1043, "sentAt": "…", "reportId": "…", "data": { … } }

// 接続した直後に1回。seq はサーバーが持っている最後の番号
{ "type": "hello", "seq": 1043, "serverTime": "…" }

// since から続きを送れなかった（REST で取り直す）
{ "type": "resync", "reason": "gap" }

接続すると hello → （since を付けたときだけ）取りこぼした分 → 以降はリアルタイム、の順に届きます。

条件の指定

WebSocket

wss://quake-api.nakn.jp/v2/ws?topics=earthquake,tsunami&minIntensity=3&since=1040

// つないだあとに条件を変える（topics と minIntensity の両方が置き換わる）
{ "type": "subscribe", "topics": ["earthquake"], "minIntensity": "4" }

• サーバーは30秒ごとに ping を送ります。pong は多くのライブラリが自動で返します。
• 切断のコード 1001（サーバーの再起動）・1013（受け取りが遅く、送信待ちが 1MB を超えた）。どちらも since を付けて再接続してください。

SSE

GET https://quake-api.nakn.jp/v2/events?topics=earthquake&minIntensity=3

id: 1044
event: earthquake
data: {"type":"earthquake","seq":1044,"sentAt":"…","reportId":"…","data":{…}}

• EventSource は切れると自動で再接続し、最後の id を Last-Event-ID で送ります。サーバーはこれを since として扱うので、取りこぼしは自動で埋まります。
• event: 付きなので、addEventListener("earthquake", …) で受け取ります。

続きから受け取る（since）

サーバーは直近 24時間、または 5,000件までのメッセージを持っています。since がその範囲の外なら resync が届き、そのあとのリアルタイムの配信はそのまま続きます。

REST

本文はデータそのものです（包みはありません）。CORS はどこからでも許可しているので、ブラウザから直接呼べます。

地震の一覧の絞り込み

一覧では、データ量を減らすため intensity.cities と intensity.stations を省いています。必要なら1件ずつ取ってください。

地震（Earthquake）

1つの地震（eventId）について、受け取った報をすべてまとめた今の状態です。震度速報 → 震源情報 → 震源・震度情報 … と報が届くたびに、まとめ直したものが配信されます。

{
  "eventId": "20080614084350",
  "status": "active",
  "version": 2,
  "updatedAt": "2008-06-14T09:01:00+09:00",
  "originTime": "2008-06-14T08:43:00+09:00",
  "hypocenter": { "code": "213", "name": "岩手県内陸南部", "latitude": 39, "longitude": 140.9, "depthKm": 10 },
  "magnitude": { "value": 7, "type": "Mj", "label": "M7.0" },
  "maxIntensity": "6+",
  "intensity": {
    "source": "VXSE53",
    "prefectures": [ { "code": "03", "name": "岩手県", "maxIntensity": "6+", "unreceived": false } ],
    "areas": [ … ], "cities": [ … ], "stations": [ … ]
  },
  "tsunami": { "risk": "none", "comment": "この地震による津波の心配はありません。" },
  "eewIssued": true,
  "reports": [ { "type": "VXSE53", "serial": 3, "infoType": "issued", … } ]
}

津波（Tsunami）

同じ地震の津波の報（津波警報・注意報・予報、津波情報、沖合の津波観測）をまとめた、1つの津波の今の状態です。

高さを表示するときは maxHeight.label（10m、10m超、巨大）を使うのが確実です。

緊急地震速報

topics=eew を指定すると届きます。受信を冗長化し、最初に届いた報をすぐ配ります。

wss://quake-api.nakn.jp/v2/ws?topics=earthquake,tsunami,eew

{ "type": "eew", "seq": 2051, "sentAt": "…", "reportId": "eew-20261102020128-6-3",
  "data": {
    "eventId": "20261102020128", "serial": 6, "version": 3, "status": "active",
    "isWarning": false, "isFinal": true, "isAssumption": false,
    "reportedAt": "2026-11-02T02:02:27+09:00", "originTime": "2026-11-02T02:01:18+09:00",
    "hypocenter": { "name": "与那国島近海", "latitude": 23.8, "longitude": 123.3, "depthKm": 10 },
    "magnitude": 4.5, "maxIntensity": "2", "areas": []
  } }

• 同じ第何報でも、あとから警報の対象地域などがそろうと version が上がって届き直します。
• minIntensity を指定しても、警報・取消は必ず届きます。

エラーと上限

{ "error": { "code": "notFound", "message": "指定した地震が見つかりません。" } }

正しく扱うために

1. version で新旧を判断する。地震は eventId、津波は id ごとに、手元より大きい version だけで置き換えます。
2. 最後の seq を覚え、再接続のときに since に付ける。（SSE の EventSource では自動）
3. resync が届いたら、REST で取り直す。
4. 再接続は少し待ってから。1秒、2秒、5秒、10秒…と間をあけ、毎回少しずらしてください。
5. 取消を反映する。status: "canceled" の地震は表示から外します。
6. null を前提に作る。震度速報だけの段階では震源がなく、震源情報だけの段階では震度がありません。

コード例

ブラウザ（SSE）

const earthquakes = new Map(); // eventId → Earthquake

function apply(item) {
  const current = earthquakes.get(item.eventId);
  if (current && current.version >= item.version) return; // 古いものは捨てる
  earthquakes.set(item.eventId, item);
  console.log(item.hypocenter?.name, item.maxIntensity, item.magnitude?.label);
}

// 1. 今の状態を取る
fetch("https://quake-api.nakn.jp/v2/earthquakes/latest")
  .then((r) => (r.ok ? r.json() : null))
  .then((item) => item && apply(item));

// 2. リアルタイムで受け取る（再接続と取りこぼしの補完はブラウザが自動でする）
const events = new EventSource("https://quake-api.nakn.jp/v2/events?topics=earthquake&minIntensity=3");
events.addEventListener("earthquake", (e) => apply(JSON.parse(e.data).data));
events.addEventListener("resync", () => location.reload());

付録：値の一覧

震度の順序

津波の category

電文の種類