防災事件 API

DPIP 防災事件 API 匯整中央氣象署、國家災害防救科技中心、經濟部水利署、行政院人事行政總處等單位發布的防災資訊，整理成同一種事件格式。可以查全國或單一鄉鎮目前生效中的事件、近 3 天的事件，以及單一事件的影響範圍（GeoJSON）。標題與內文可依 lang 參數取得簡體中文、英文、日文等語言。

資料授權

註明來源・可商用
建議標示資料來源：中央氣象署等發布機關、ExpTech Studio（exptech.dev）

上游條款

中央氣象署、國家災害防救科技中心、經濟部水利署、行政院人事行政總處等發布機關：各發布機關的資料使用規範同樣適用。每個事件的發布單位見 author 欄位，單獨顯示一個事件時建議一併標示該單位。

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

驗證

目前不需要 API Token。

區域碼

region 路徑參數與事件的 area 欄位都使用鄉鎮市區的 3 碼郵遞區號，例如 105 是臺北市松山區、970 是花蓮縣花蓮市。與鄉鎮逐時預報的鄉鎮碼相同。

鄉鎮端點只回 area 含該碼的事件，不必自己篩選。
area 為 [] 的事件（例如以多邊形表示範圍的大雷雨、道路封閉）只會出現在全國端點。這類事件請用 hasPolygon 與 /event/{id} 取得範圍自行判斷。

語言

五支端點都接受查詢參數 lang，一次一種語言。不帶、空白或無法辨識都當作 zh，不會回 400。

`lang`	語言	轉換方式
`zh`	繁體中文（臺灣）	原文
`zh_Hant_HK`	繁體中文（香港）	請求當下轉換
`zh_Hans`	简体中文	請求當下轉換
`en`	English	背景翻譯
`ja`	日本語	背景翻譯
`ko`	한국어	背景翻譯
`vi`	Tiếng Việt	背景翻譯
`th`	ไทย	背景翻譯
`id`	Bahasa Indonesia	背景翻譯
`fil`	Filipino	背景翻譯

解析規則：

有多個值時只取第一個；有逗號時只取第一段（en,ja 視為 en）。
去掉前後空白，- 換成 _（zh-TW 等於 zh_TW）。
與上表完全相同就採用。
別名（不分大小寫）：zh_TW、zh_Hant、zh_Hant_TW → zh；yue、zh_HK、yue_Hant、zh_Hant_MO → zh_Hant_HK；zh_CN、zh_SG、zh_Hans_CN → zh_Hans。
否則取第一個 _ 前的主語言，在上表內就採用（en_US → en、ja_JP → ja）。
其餘一律 zh。

只有 title、subtitle、description 會轉換或翻譯，raw 永遠是臺灣正體原文。背景翻譯的語言若三個欄位缺任何一段譯文，這一筆會整筆退回 zh（lang 欄位為 zh），不會中外文夾雜；稍後再請求同一網址就會拿到譯文，ETag 也會改變。要判斷譯文是否就緒，比較每筆的 lang 與請求的語言即可。

取得全國生效中的事件

全國目前尚未到期（expires 大於現在）的事件。不含多邊形範圍。

GEThttps://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/list

可商用

伺服器TNN-1

Query 參數

langstring選填預設 zh
查詢參數。語言，見「語言」一節

請求範例

curl "https://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/list"

const res = await fetch("https://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/list");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/list",
    timeout=10,
)
res.raise_for_status()
print(res.json())

回應

200304

成功；沒有事件時為 []

[
  {
    "id": "1794632460",
    "status": 1,
    "type": "thunderstorm",
    "author": "cwa",
    "send": 1794632400000,
    "expires": 1794636000000,
    "title": "大雷雨即時訊息",
    "subtitle": "雷雨即時訊息",
    "description": "氣象署發布大雷雨即時訊息，持續時間至 14 時。",
    "lang": "zh",
    "area": [],
    "hasPolygon": true
  }
]

資料未變更（If-None-Match 相符），沒有 body沒有回應本文

試試看

回應欄位

回應是事件陣列。四支列表端點的每一筆都是這個形狀。

欄位	類型	說明
`[].id`	`string`	事件識別碼。由數字組成的字串（寫入當下的 Unix 秒），全域唯一。單位與 send 不同，不要拿來當時間
`[].status`	`number`	1：來源標示為正式發布；0：其他（例如演習、測試）
`[].type`	`string`	事件類型，見「事件類型」
`[].author`	`string`	發布來源識別，例如 cwa、ncdr、wra、dgpa；部分類型直接取自來源資料，格式不固定
`[].send`	`number`	發布時間，Unix 毫秒
`[].expires`	`number`	到期時間，Unix 毫秒
`[].title`	`string`	標題
`[].subtitle`	`string`	副標題
`[].description`	`string`	內文。鄉鎮端點可能是該鄉鎮的摘要，見「description 與 raw」
`[].raw`	`string`	選填。全國原文，只有鄉鎮端點且 description 用了該鄉鎮摘要時才出現；不翻譯
`[].lang`	`string`	這一筆實際採用的語言；譯文未齊時為 zh
`[].area`	`number[]`	影響的鄉鎮區域碼（3 碼郵遞區號），可為 []
`[].hasPolygon`	`boolean`	true 表示可用 /event/{id} 取得多邊形範圍
`[].addition`	`object`	選填。依類型附加的資料，見「附加資料 addition」

取得指定鄉鎮生效中的事件

area 含指定鄉鎮、而且在該鄉鎮尚未到期的事件。

GEThttps://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/{region}

可商用

伺服器TNN-1

路徑參數

regioninteger必填
路徑參數。3 碼郵遞區號，例如 105

Query 參數

langstring選填預設 zh
查詢參數。語言

請求範例

curl "https://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/<region>"

const res = await fetch("https://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/<region>");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.core-tnn1.exptech.dev/api/v2/dpip/realtime/<region>",
    timeout=10,
)
res.raise_for_status()
print(res.json())

回應

200304400

成功；沒有事件時為 []

[
  {
    "id": "1794626412",
    "status": 1,
    "type": "heavy-rain",
    "author": "cwa",
    "send": 1794626400000,
    "expires": 1794662400000,
    "title": "大雨特報",
    "subtitle": "大雨特報",
    "description": "臺北市松山區今晚有局部大雨，請注意。",
    "raw": "東北風影響，今（14）日基隆北海岸、臺北市山區及新北市山區有局部大雨發生的機率。",
    "lang": "zh",
    "area": [
      105,
      106,
      110
    ],
    "hasPolygon": false
  }
]

資料未變更（If-None-Match 相符），沒有 body沒有回應本文

region 不是數字

{
  "error": "Invalid region"
}

試試看

回應欄位

同全國生效中的事件。差別在 description 與 raw，見description 與 raw。

取得全國近 3 天的事件

全國 send 在最近 3 天內的事件，包含已到期的。

GEThttps://api.core-tnn1.exptech.dev/api/v2/dpip/history/list

可商用

伺服器TNN-1

Query 參數

langstring選填預設 zh
查詢參數。語言

請求範例

curl "https://api.core-tnn1.exptech.dev/api/v2/dpip/history/list"

const res = await fetch("https://api.core-tnn1.exptech.dev/api/v2/dpip/history/list");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.core-tnn1.exptech.dev/api/v2/dpip/history/list",
    timeout=10,
)
res.raise_for_status()
print(res.json())

回應

200304

成功；沒有事件時為 []

[
  {
    "id": "1794630005",
    "status": 1,
    "type": "earthquake",
    "author": "cwa",
    "send": 1794630005000,
    "expires": 1794716405000,
    "title": "地震報告",
    "subtitle": "地震報告 [115071]",
    "description": "11/14 12:16左右，花蓮縣近海發生地震。震源深度15公里，地震規模M5.1，花蓮縣觀測到最大震度4級。",
    "lang": "zh",
    "area": [
      970,
      971,
      972
    ],
    "hasPolygon": false,
    "addition": {
      "id": "115071-2026-1114-121630"
    }
  }
]

資料未變更（If-None-Match 相符），沒有 body沒有回應本文

試試看

回應欄位

同全國生效中的事件。

取得指定鄉鎮近 3 天的事件

area 含指定鄉鎮、send 在最近 3 天內的事件，包含已到期的。

GEThttps://api.core-tnn1.exptech.dev/api/v2/dpip/history/{region}

可商用

伺服器TNN-1

路徑參數

regioninteger必填
路徑參數。3 碼郵遞區號，例如 105

Query 參數

langstring選填預設 zh
查詢參數。語言

請求範例

curl "https://api.core-tnn1.exptech.dev/api/v2/dpip/history/<region>"

const res = await fetch("https://api.core-tnn1.exptech.dev/api/v2/dpip/history/<region>");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.core-tnn1.exptech.dev/api/v2/dpip/history/<region>",
    timeout=10,
)
res.raise_for_status()
print(res.json())

回應

200304400

成功；沒有事件時為 []

[
  {
    "id": "1794626412",
    "status": 1,
    "type": "heavy-rain",
    "author": "cwa",
    "send": 1794626400000,
    "expires": 1794662400000,
    "title": "Heavy Rain Advisory",
    "subtitle": "Heavy Rain Advisory",
    "description": "Localized heavy rain is expected in Songshan District, Taipei tonight.",
    "raw": "東北風影響，今（14）日基隆北海岸、臺北市山區及新北市山區有局部大雨發生的機率。",
    "lang": "en",
    "area": [
      105,
      106,
      110
    ],
    "hasPolygon": false
  }
]

資料未變更（If-None-Match 相符），沒有 body沒有回應本文

region 不是數字

{
  "error": "Invalid region"
}

試試看

回應欄位

同全國生效中的事件。上例為 ?lang=en：raw 仍是中文原文。

取得單一事件

依 id 取得一筆事件；有範圍時多一個 polygon（GeoJSON）。列表沒有 polygon，hasPolygon 為 true 時再用這支取得。

GEThttps://api.core-tnn1.exptech.dev/api/v2/dpip/event/{id}

可商用

伺服器TNN-1

路徑參數

idstring必填
路徑參數。事件的 id

Query 參數

langstring選填預設 zh
查詢參數。語言

請求範例

curl "https://api.core-tnn1.exptech.dev/api/v2/dpip/event/<id>"

const res = await fetch("https://api.core-tnn1.exptech.dev/api/v2/dpip/event/<id>");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.core-tnn1.exptech.dev/api/v2/dpip/event/<id>",
    timeout=10,
)
res.raise_for_status()
print(res.json())

回應

200304

成功；查無此 id 時為 []

[
  {
    "id": "1794632460",
    "status": 1,
    "type": "thunderstorm",
    "author": "cwa",
    "send": 1794632400000,
    "expires": 1794636000000,
    "title": "大雷雨即時訊息",
    "subtitle": "雷雨即時訊息",
    "description": "氣象署發布大雷雨即時訊息，持續時間至 14 時。",
    "lang": "zh",
    "area": [],
    "hasPolygon": true,
    "polygon": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [
                  121.56,
                  25.03
                ],
                [
                  121.57,
                  25.04
                ],
                [
                  121.58,
                  25.02
                ],
                [
                  121.56,
                  25.03
                ]
              ]
            ]
          }
        }
      ]
    }
  }
]

資料未變更（If-None-Match 相符），沒有 body沒有回應本文

試試看

回應欄位

回應是陣列，正常是一筆，查無時為 []（200）。欄位同全國生效中的事件，另外：

欄位	類型	說明
`[].polygon`	`object`	選填。GeoJSON FeatureCollection，geometry 為 Polygon，座標 [經度, 緯度]；只在 hasPolygon 為 true 時出現。幾何已簡化（誤差約 22 m）

description 的選擇規則與全國端點相同（全國原文，不帶 raw）。

事件類型

以下是目前會寫入事件的類型。未列出的類型也請照常顯示（用通用圖示），不要丟棄該筆。

`type`	名稱	`author`	`area`	範圍 `polygon`	`addition`	備註
`heavy-rain`	大雨特報	`cwa`	鄉鎮碼	無	無	有逐區摘要
`extremely-heavy-rain`	豪雨特報	`cwa`	鄉鎮碼	無	無	有逐區摘要
`torrential-rain`	大豪雨特報	`cwa`	鄉鎮碼	無	無	有逐區摘要
`extremely-torrential-rain`	超大豪雨特報	`cwa`	鄉鎮碼	無	無	有逐區摘要
`thunderstorm`	大雷雨即時訊息、龍捲風注意	`cwa`	`[]`	有	無	標題為「大雷雨即時訊息」或「龍捲風注意」
`earthquake`	地震報告	`cwa`	有觀測到震度的縣市的全部鄉鎮	無	地震報告編號	到期時間為發布後 24 小時
`tsunami_note`	若干海面變動	`cwa`	沿海鄉鎮	無	地震報告編號	規模 6 以上、深度 30 公里以內且震央在海域時發布；到期時間為發布後 24 小時
`debrisFlowLandSlide`	土石流及大規模崩塌警戒	來源發布單位	`[]`	有	無
`barrierLake`	堰塞湖警戒	來源發布單位	`[]`	有	無
`roadClose`	道路封閉	來源發布單位	`[]`	有	封閉位置
`floodSensor`	淹水感測	`wra`	`[]`	有	感測站
`seawave`	海浪觀測（巨浪）	`ncdr`	`[]`	有	無	沿海測站波高 6 公尺以上時發布；到期時間為觀測後 3 小時
`workSchlClos`	停班停課	`dgpa`	鄉鎮碼	無	無
`reservoirDischarge`	水庫放流	`wra`	鄉鎮碼	無	無	目前未啟用，不會出現

降雨特報由輕到重：heavy-rain、extremely-heavy-rain、torrential-rain、extremely-torrential-rain。

附加資料 addition

只有部分類型帶 addition，欄位都可能省略：

類型	形狀
`earthquake`、`tsunami_note`	`{ "id": "地震報告編號" }`，可用於地震報告
`roadClose`	`areaDesc`（範圍描述）、`county`、`town`、`roadName`、`location`、`geocode`，以及來源原文的 `polygon`、`circle` 字串
`floodSensor`	`areaDesc`、`county`、`town`、`waterLevelStation`（水位站）、`waterLevel`（水位）、`geocode`，以及來源原文的 `polygon`、`circle` 字串

addition 裡的 polygon、circle 是來源的原始字串；畫地圖請用 /event/{id} 的 GeoJSON polygon。

description 與 raw

四種降雨特報（heavy-rain、extremely-heavy-rain、torrential-rain、extremely-torrential-rain）除了全國原文，還有自動產生的逐區摘要。

端點	一般事件	降雨特報
全國列表、`/event/{id}`	`description` 是原文，沒有 `raw`	`description` 是全國原文，沒有 `raw`
鄉鎮列表，且該鄉鎮有逐區摘要	不會發生	`description` 是該鄉鎮摘要，`raw` 是全國原文
鄉鎮列表，但該鄉鎮沒有逐區摘要	`description` 是原文，沒有 `raw`	`description` 是全國原文，沒有 `raw`

降雨特報會先以原文出現，逐區摘要稍後（通常幾分鐘內）才補上，所以同一個 id 的 description 可能改變。請以最新一次回應為準，不要用 id 快取內文。外語請求時，若該鄉鎮摘要還沒有譯文，description 會先用全國原文的譯文。

進階範例

在 MapLibre GL JS 畫出全國生效中事件的範圍：列表沒有 polygon，hasPolygon 為 true 的事件要再查單一事件取得 GeoJSON。

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

// 1. 全國生效中的事件，依發布時間由新到舊排序（回應順序沒有保證）
const events = await fetch(`${API}/api/v2/dpip/realtime/list`).then((r) => r.json());
events.sort((a, b) => b.send - a.send);

// 2. 有範圍的事件再查單一事件，把 polygon 加成 GeoJSON source
for (const e of events.filter((e) => e.hasPolygon)) {
  const [event] = await fetch(`${API}/api/v2/dpip/event/${e.id}`).then((r) => r.json());
  if (!event?.polygon) continue; // 查無此事件時回 []
  map.addSource(`dpip-${event.id}`, { type: "geojson", data: event.polygon });
  map.addLayer({
    id: `dpip-${event.id}`,
    type: "fill",
    source: `dpip-${event.id}`,
    paint: { "fill-color": "#ef4444", "fill-opacity": 0.25 },
  });
}

注意事項

時間單位：send、expires 是 Unix 毫秒；id 雖然也是時間數字，但是 Unix 秒，而且只是識別碼。
回應順序沒有保證，請自行依 send 由新到舊排序。
查無資料一律回 []（200），不是 404。只有 region 不是數字時回 400。
生效中與近 3 天的條件不同：已到期但 3 天內發布的只在 history；尚未到期但超過 3 天前發布的只在 realtime。
事件最多保留 7 天，超過後 /event/{id} 也查不到。
回應帶 ETag（不加引號的 MD5）。If-None-Match 加不加引號都可以，相符時回 304，沒有 body。ETag 涵蓋整份回應，包含語言與當下的譯文，所以快取 key 請包含完整網址（含 lang）。伺服器不送 Cache-Control。
回應支援 gzip（curl 加 --compressed），允許跨網域呼叫。
資料來源：中央氣象署、國家災害防救科技中心、經濟部水利署、行政院人事行政總處等單位的公開防災資訊。