気象 API の概要

気象 API（v5）は、台湾の観測点の天気、雨量、雷、台風、ならびに最寄りの観測点の現在の天気と市区町村の 1 時間ごとの予報を提供します。データは交通部中央気象署からのもので、サーバーが定期的に取得し、簡潔な JSON に整えます。エンドポイントはすべて GET で、プレフィックスは /api/v5/meteor です。

データライセンス

• 出典明記・商用可

  推奨表記データ出典：中央気象署、ExpTech Studio（exptech.dev）

上流の条件

• 中央気象署：中央気象署のデータ利用規約（政府データオープンライセンスなど）も適用されます。気象・地震情報は中央気象署の発表を正とします。

表記の場所、例、商用利用の申請はデータの利用条件と出典表記をご覧ください。

認証

現在は API Token は不要で、別のアクセス制限もありません。

データセット

データセット	ページ	内容	更新の頻度	履歴の保持
観測点の天気 weather	観測点の天気	自動気象観測点の気温、湿度、気圧、風、最大瞬間風速、その日の最高・最低気温	約 1 時間に 1 件	3 日。推移は最大 7 日
現在の天気 weather/realtime	観測点の天気	指定座標に最も近い観測点の現在の天気	1 分ごとに確認	最新値だけ
市区町村予報 weather/forecast	観測点の天気	市区町村の今後約 24 時間の 1 時間ごとの予報	15 分ごと	最新値だけ
雨量 rain	雨量	雨量観測点の、時間区分ごとの積算雨量	約 10 分ごと	3 日。推移は最大 7 日
雷 lightning	雷	雲対雲、雲対地の雷の位置と時刻	30 秒ごとに確認	3 日
台風 typhoon	台風	進路、予報円、暴風域に入る確率、台風警報	1 分ごとに確認	7 日。各種少なくとも最新 1 件

「1 分ごとに確認」は、サーバーがその頻度で出典を照会し、出典に新しいデータがあるときだけ 1 件増やす、という意味です。

サーバーと Base URL

気象 API は TNN-1 ノードだけにあり、パスによって 2 台のサーバーに分かれます。

パス	サーバー	キャッシュ
末尾が 10 桁の Unix 秒であるスナップショット。例：/api/v5/meteor/weather/1794636000、/api/v5/meteor/typhoon/track/1794636000	https://static.core-tnn1.exptech.dev	300 秒（404 は 5 秒）
それ以外のすべてのパス。最新値、/list、/station、/trend/...、/realtime/...、/forecast/...、/typhoon/geojson	https://api.core-tnn1.exptech.dev	1 秒

• サーバーを間違えると 404 です。api.core はタイムスタンプ付きスナップショットのパスに必ず 404 を返し、static.core はタイムスタンプ付きスナップショットのパスだけを提供します。
• DNS がノードを割り当てる api.core.exptech.dev や static.core.exptech.dev は使わないでください。TNN-1 以外のノードに割り当てられると、気象のパスはすべて 404 になります。上の表の TNN-1 の URL を直接使ってください。各気象ページの例も、この 2 つの URL を使っています。
• 旧版 v3（非推奨）は https://tnn.exptech.dev にあります。旧版 v3を参照してください。

共通の形式

エンドポイントの型

weather、rain、lightning、および台風の 4 種のデータは、同じ型を使います。

型	パス	レスポンス
最新	/api/v5/meteor/<データセット>	最新の 1 件のスナップショット
時刻リスト	/api/v5/meteor/<データセット>/list	照会できるスナップショットの時刻。差分符号化（下記）
指定時刻	/api/v5/meteor/<データセット>/<10 桁の Unix 秒>	その時刻のスナップショット。構造は「最新」と同じ。static.core だけ
推移	/api/v5/meteor/<データセット>/trend/<観測点 ID>	単一観測点の 24 時間または 7 日の系列（天気、雨量）
観測点一覧	/api/v5/meteor/<データセット>/station	観測点 ID に対応する名称、県・市、郷鎮、標高、座標（天気、雨量）

指定時刻のスナップショットは、/list に出た時刻を使ってください。それ以外の時刻は必ず 404 です。

フィールドごとの配列

天気、雨量、雷のスナップショットは「観測点ごとに 1 オブジェクト」ではありません。フィールドごとに 1 配列で、配列の添字は互いに揃います。天気と雨量は ids[i] で観測点一覧に対応させ、名称と座標を得ます。観測点一覧はめったに変わらないので、一度取得したあとは ETag で確認すれば足ります。

const API = "https://api.core-tnn1.exptech.dev";

const [station, latest] = await Promise.all([
  fetch(`${API}/api/v5/meteor/weather/station`).then((r) => r.json()),
  fetch(`${API}/api/v5/meteor/weather`).then((r) => r.json()),
]);

const rows = latest.ids.map((id, i) => ({
  id,
  name: station[id]?.n,
  county: station[id]?.c,
  temp: latest.temp[i] === -99 ? null : latest.temp[i],
}));

差分の時刻リスト

/list と推移の ts は、差分符号化の Unix 秒です。最初の要素が開始時刻で、それ以降の各要素は直前の時刻との差（秒）です。古い順です。

[1794632400, 3600, 3600]

これは 1794632400、1794636000、1794639600 の 3 つの時刻を表します。復元方法は次のとおりです。

function decodeDelta(a) {
  const out = [];
  let t = 0;
  for (let i = 0; i < a.length; i++) {
    t = i === 0 ? a[0] : t + a[i];
    out.push(t);
  }
  return out;
}

データがないときは [] を返します。

時刻

• v5 の時刻はすべて Unix 秒（10 桁）です。パスの <time> も秒です。
• 例外：市区町村予報の updateTime は Unix ミリ秒（13 桁）です。forecast[].time は台湾時間の "HH:00" という文字列です。
• 旧版 v3 の time は Unix ミリ秒です。

単位

量	単位
気温、体感温度	°C
相対湿度、降水確率	%
気圧	hPa
風速、最大瞬間風速	m/s。台風の進行速度は km/h
風向	度（観測点のスナップショット）。文字列（現在の天気、予報、台風）
雨量	mm
距離、台風の暴風半径	km
標高	m
座標	十進度。小数第 4 位に四捨五入

天気、雨量、雷は lat / lon の 2 フィールドです。台風の幾何座標は GeoJSON の順 [経度, 緯度] です。

欠測

データ	表し方
観測点の天気、雨量、現在の天気の数値フィールド	-99。雨量は負にならないため、負の値は有効な観測がないものとして扱います
観測点スナップショットの gt、hit、lot（時刻）	0
天気コード wx、weatherCode	0
市区町村予報	気温、体感温度、湿度は -99。降水確率、風速、風力階級は 0。風向は ""
台風	null

天気コード

観測点スナップショットの wx、現在の天気と予報の weatherCode は、この 3 桁のコードを使います。百の位が雲量、下 2 桁が付随現象です。

百の位	雲量
1	晴れ
2	曇り
3	本曇り

下 2 桁	現象	下 2 桁	現象
00	付随現象なし、または対応できない	10	氷あられ
01	煙霧	11	にわか雨
02	もや	12	にわかみぞれ
03	雷光	13	ひょう
04	雷鳴	14	雷雨
05	霧	15	雷を伴う雪
06	雨	16	雷を伴うひょう
07	みぞれ	17	激しい雷雨
08	大雪	18	激しい雷を伴うひょう
09	雪あられ	19	雷

たとえば 206 は「曇りで雨」です。天気の文の先頭が晴れ、曇り、本曇りのいずれでもないとき、またはデータがないときは 0 です。

キャッシュと条件付きリクエスト

• v5 の JSON レスポンスにはすべて ETag（引用符付きの MD5）が付きます。前回の値を If-None-Match に入れると、データが変わっていないときは 304 で、body はありません。
• レスポンスは gzip に対応しています。リクエストに Accept-Encoding: gzip を付けてください（curl は --compressed）。
• どのオリジンからでもクロスオリジンで呼べます（Access-Control-Allow-Origin: *）。ブラウザから直接 fetch できます。
• サーバー側のキャッシュは、api.core が 1 秒、static.core が 300 秒です。

データ出典

データセット	出典
観測点の天気、雨量、雷、台風	交通部中央気象署のオープンデータ
現在の天気、市区町村予報	交通部中央気象署のウェブサイトの、観測点観測と市区町村予報

転載または表示するときは、データライセンスの推奨表記で出典を表示してください。