這份文件是什麼
本站把各地方政府與公路局依法主動公開的公告整理成可檢索的形式。此頁說明如何用程式取用同一份資料：公開資料 API（v1）提供 JSON，RSS提供訂閱用的 feed。兩者都是唯讀，不需要申請金鑰、不需要註冊。
機器可讀的介面描述：OpenAPI 3.1 文件（/api/openapi.json）。本頁內容與該檔以同一份實作為準。
端點一覽
| 路徑 | 用途 | 參數 | 回應主要欄位 |
|---|---|---|---|
/api/v1/records |
分頁列表，排序 publish_date DESC, id ASC |
page（≥1，預設 1）、per_page（10–200，預設 50）、county（縣市代碼，大寫）、since / until（YYYY-MM-DD，比對公告日，閉區間）、q（關鍵字） |
api_version、page、per_page、total、total_pages、filters、rows[] |
/api/v1/records/<id> |
單筆記錄 | id 須為 16 碼小寫十六進位字串；格式不符回 400，格式正確但查無資料回 404 |
api_version、record |
/api/v1/counties |
縣市清單與各縣筆數 | 無 | api_version、counties[]（code、zh、region、total_records、last_publish_date、rss_url） |
/api/v1/latest |
最新 N 筆（/api/v1/records 的輕量版，資料列形狀相同） |
limit（1–100，預設 20）、county（選用） |
api_version、limit、count、filters、rows[] |
參數處理慣例：數值型參數超出範圍一律夾到邊界值（不報錯）；只有語法明確錯誤才回 400 —— 日期非 YYYY-MM-DD、county 不是有效縣市代碼、id 格式不符。
curl 範例
列表（第 1 頁，每頁 50 筆）：
curl -s "https://traffic.i23iv.cc/api/v1/records?page=1&per_page=50"單筆記錄：
curl -s "https://traffic.i23iv.cc/api/v1/records/075bfed18688a160"縣市清單：
curl -s "https://traffic.i23iv.cc/api/v1/counties"最新 5 筆（限臺北市）：
curl -s "https://traffic.i23iv.cc/api/v1/latest?limit=5&county=TPE"縣市代碼可由 /api/v1/counties 取得（例：TPE、NWT、TYC、TXG、KHH）。
record 欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string | 16 碼小寫十六進位；同一筆公告的穩定識別碼 |
county | string | 縣市代碼（大寫） |
county_zh | string | 縣市中文名 |
name | string | 公告所載姓名 |
publish_date | string / null | 公告日（YYYY-MM-DD） |
violation_date | string / null | 公告揭示的違規日期欄位（YYYY-MM-DD） |
incident_date | string / null | 事件發生日（YYYY-MM-DD） |
location | string / null | 公告所載地點原文 |
district | string / null | 由地點推得的鄉鎮市區（未能判定時為 null） |
announcement | string / null | 公告事由原文（含換行） |
photo_path | string / null | 本站保存的公告截圖路徑（相對路徑） |
source_url | string / null | 政府原始公告頁網址 |
source_file | string / null | 本站抓取批次的來源檔名 |
fetched_at | string / null | 本站抓取時間，ISO 8601 帶 +08:00 |
geo_lat / geo_lng | number / null | 地點座標（未定位時為 null） |
geo_precision | string / null | 座標精度層級 |
record_url | string | 本站對應的單筆頁面網址 |
時間一律台灣時間 +08:00：所有日期欄位（publish_date、violation_date、incident_date）都是台灣當地日期；fetched_at 為 ISO 8601 字串並明帶 +08:00 位移。請勿假設為 UTC。
姓名未遮罩，與政府原始公告一致：name 欄位照政府公告原文輸出，本站不做遮罩、不做人別比對、不補充任何外部資料。使用時請一併遵守《個人資料保護法》相關規定，並以政府原始公告為準。
錯誤格式
除 429 外，非 2xx 回應一律為扁平兩鍵 JSON；429 的 body 不帶 message，改帶 retry_after_sec（與 Retry-After 標頭同值）：
{"error":"invalid_parameter","message":"county 不是有效的縣市代碼：XXX"}
{"error":"rate_limit_exceeded","retry_after_sec":37}| 狀態碼 | error | 時機 |
|---|---|---|
| 400 | invalid_parameter | 參數語法錯誤（日期格式、縣市代碼、id 格式） |
| 404 | not_found | 查無該筆記錄，或不存在的 v1 端點 |
| 429 | rate_limit_exceeded | 超出流量限制（見下節）；body 為 error + retry_after_sec，無 message |
| 503 | database_unavailable | 資料庫暫時無法存取 |
RSS 訂閱
| 路徑 | 內容 |
|---|---|
/rss.xml | 全站最新 50 筆公告 |
/rss/<COUNTY_CODE>.xml | 單一縣市最新 50 筆，<COUNTY_CODE> 為大寫縣市代碼（例 /rss/TPE.xml） |
- 格式 RSS 2.0，
Content-Type: application/rss+xml; charset=utf-8。 - 每筆
<guid>使用記錄id（穩定不變），<pubDate>為公告日的台灣時間（+0800）。 - 伺服器端快取 300 秒，同一份 feed 在該期間內回傳相同內容；請勿以高於此頻率輪詢。回應另帶
Cache-Control: public, max-age=900，用戶端與邊緣快取最長可留存 900 秒，因此實際看到的內容可能比伺服器端新鮮度再舊一些。 - 未知的縣市代碼回 404。有效代碼可由
/api/v1/counties的rss_url欄位取得。 - feed 不列入
sitemap.xml，改由首頁與縣市頁的<link rel="alternate">供閱讀器自動發現。
curl -s "https://traffic.i23iv.cc/rss.xml"
curl -s "https://traffic.i23iv.cc/rss/TPE.xml"CORS
/api/v1/* 是公開唯讀資料，回應一律帶 Access-Control-Allow-Origin: *，瀏覽器端可直接跨網域取用，不需代理。
其餘端點（例如站台自用的 /api/search、/api/metrics/*）不帶此標頭，預設同源使用；這些路徑的形狀可能隨站台前端調整，請以 /api/v1/* 作為對外介接對象。
流量限制
以 /api/ 為前綴的路徑套用每個來源 IP 每 60 秒 600 次請求的滑動視窗限制，超出時回 429。健康檢查端點（/api/health、/api/healthz）豁免。
HTML 頁面、站台根目錄下的靜態檔與 /rss*.xml 不計入此額度；feed 改以伺服器端 300 秒快取控制負載。例外：限流以路徑前綴判斷，因此位於 /api/ 前綴下的靜態檔（例如 /api/openapi.json）仍計入額度，回應會帶 X-RateLimit-* 標頭。若需大量批次取用，建議以 per_page=200 分頁取代高頻小量請求。
版本策略
- 路徑前綴固定為
/api/v1，每個回應同時帶api_version欄位。 - 不提供無版本別名（
/api/records不存在），避免日後語意漂移。 - 相容性變更（新增欄位、新增選用參數）直接在 v1 內進行，請以「忽略未知欄位」的方式解析。
- 破壞性變更會另開
/api/v2，v1 保留，不就地改變既有欄位的名稱或型別。
資料來源與引用建議
本站資料 100% 取自政府主動公開的網頁：交通部公路總局 酒駕累犯公布專區及各監理所、直轄市政府交通局的公告專區。詳細來源清單見公告來源總覽。
引用時建議一併註明：資料原始出處（該筆的 source_url）、公告日（publish_date）、以及取用時間。本站僅做彙整與索引，不新增、不評價、不加註；資料正確性以政府公布為準，更正與下架流程見法律聲明與常見問題。
介面與整合邏輯採 CC BY-NC-SA 4.0 授權；政府公告本身的再利用條件依《政府資訊公開法》與各機關規定辦理。