跳到內容
ExpTech StudioExpTech
主控台

氣象 API 概要

氣象 API（v5）提供臺灣的測站天氣觀測、雨量、閃電、颱風，以及最近測站即時天氣與鄉鎮逐時預報。資料來自交通部中央氣象署，伺服器定時抓取後整理成精簡的 JSON。全部端點都是 GET，前綴是 /api/v5/meteor。

資料授權

Section titled “資料授權”
上游條款
  • 中央氣象署：另須遵守中央氣象署的資料使用規範（例如政府資料開放授權條款）；氣象與地震資訊以中央氣象署發布的內容為準。

標示位置、範例與商業使用申請見資料授權與來源標示。

驗證

Section titled “驗證”

目前不需要 API Token，也沒有另外的存取限制。

資料集

Section titled “資料集”
資料集 頁面 內容 更新頻率 歷史保留
測站天氣 weather 測站天氣 自動氣象站的溫度、濕度、氣壓、風、陣風、當日高低溫 約每小時一筆 3 天；趨勢最多 7 天
即時天氣 weather/realtime 測站天氣 離指定座標最近的測站目前天氣 每分鐘檢查 只有最新值
鄉鎮預報 weather/forecast 測站天氣 鄉鎮未來約 24 小時的逐時預報 每 15 分鐘 只有最新值
雨量 rain 雨量 雨量站各累積時距的雨量 約每 10 分鐘 3 天；趨勢最多 7 天
閃電 lightning 閃電 雲對雲、雲對地閃電的位置與時間 每 30 秒檢查 3 天
颱風 typhoon 颱風 路徑、路徑潛勢、暴風圈侵襲機率、颱風警報 每分鐘檢查 7 天，每類至少保留最新一筆

「每分鐘檢查」表示伺服器會照這個頻率向來源查詢，來源有新資料時才會新增一筆。

伺服器與 Base URL

Section titled “伺服器與 Base URL”

氣象 API 只部署在 TNN-1 節點，而且依路徑分成兩台伺服器：

路徑 伺服器 快取
結尾是 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 網址，各氣象頁的範例也都用這兩個網址。
  • 舊版 v3（已棄用）在 https://tnn.exptech.dev，見舊版 v3。

共通格式

Section titled “共通格式”

端點型態

Section titled “端點型態”

weather、rain、lightning 與颱風的四種資料都用同一組型態：

型態 路徑 回應
最新 /api/v5/meteor/<資料集> 最新一筆快照
時間列表 /api/v5/meteor/<資料集>/list 可查詢的快照時間，差量編碼（見下）
指定時刻 /api/v5/meteor/<資料集>/<10 位 Unix 秒> 該時刻的快照，結構與「最新」相同；只在 static.core
趨勢 /api/v5/meteor/<資料集>/trend/<站號> 單一測站 24 小時或 7 天的序列（天氣、雨量）
測站目錄 /api/v5/meteor/<資料集>/station 站號對應名稱、縣市、鄉鎮、海拔、座標（天氣、雨量）

指定時刻快照要用 /list 裡出現過的時間，其他時間一律回 404。

欄位化快照

Section titled “欄位化快照”

天氣、雨量、閃電的快照不是「每站一個物件」，而是每個欄位一個陣列，陣列索引互相對齊。天氣與雨量用 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],
}));

差量時間列表

Section titled “差量時間列表”

/list 與趨勢的 ts 是差量編碼的 Unix 秒：第一個元素是起始時間，之後每個元素是與前一個時間的差（秒）。時間由舊到新。

[1794632400, 3600, 3600]

代表 1794632400、1794636000、1794639600 三個時間。還原方式：

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;
}

沒有資料時回 []。

時間

Section titled “時間”
  • v5 的時間都是 Unix 秒（10 位數）。路徑上的 <time> 也是秒。
  • 例外：鄉鎮預報的 updateTime 是 Unix 毫秒（13 位數），forecast[].time 是臺灣時間的 "HH:00" 字串。
  • 舊版 v3 的 time 是 Unix 毫秒。

單位

Section titled “單位”
量 單位
氣溫、體感溫度 °C
相對濕度、降雨機率 %
氣壓 hPa
風速、陣風 m/s；颱風移速是 km/h
風向 度（測站快照）；字串（即時天氣、預報、颱風）
雨量 mm
距離、颱風暴風半徑 km
海拔 m
座標 十進位度，四捨五入到小數 4 位

天氣、雨量、閃電用 lat / lon 兩個欄位。颱風的幾何座標是 GeoJSON 順序 [經度, 緯度]。

缺值

Section titled “缺值”
資料 表示法
測站天氣、雨量、即時天氣的數值欄位 -99。雨量不會是負數，任何負值都當作沒有有效觀測
測站快照的 gt、hit、lot（時刻） 0
天氣代碼 wx、weatherCode 0
鄉鎮預報 溫度、體感溫度、濕度為 -99；降雨機率、風速、風級為 0；風向為 ""
颱風 null

天氣代碼

Section titled “天氣代碼”

測站快照的 wx、即時天氣與預報的 weatherCode 都用這套三位數代碼。百位是雲量，後兩位是附加現象。

百位 雲量
1 晴
2 多雲
3 陰
後兩位 現象 後兩位 現象
00 無附加現象或無法對應 10 有冰珠
01 有霾 11 有陣雨
02 有靄 12 陣雨雪
03 有閃電 13 有雹
04 有雷聲 14 有雷雨
05 有霧 15 有雷雪
06 有雨 16 有雷雹
07 有雨雪 17 大雷雨
08 有大雪 18 大雷雹
09 有雪珠 19 有雷

例如 206 是「多雲有雨」。天氣文字開頭不是晴、多雲、陰，或沒有資料時為 0。

快取與條件請求

Section titled “快取與條件請求”
  • 所有 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 秒。

資料來源

Section titled “資料來源”
資料集 來源
測站天氣、雨量、閃電、颱風 交通部中央氣象署開放資料
即時天氣、鄉鎮預報 交通部中央氣象署網站的測站觀測與鄉鎮預報

轉載或顯示資料時，請照資料授權的建議標示註明來源。