API v2 使用說明

API v2 使用與格式說明文檔

1. 簡介 (Introduction)

本 API 提供香港自殺報道資料庫 (HKSPD) 的公開查詢服務。系統基於 Cloudflare Workers 構建，支援高併發請求，具備智慧快取、跨域資源共享 (CORS) 及多維度數據篩選功能。

• 基礎接口 (Base URL): https://hkspd.siuyeong.com/api_v2
• 請求方法 (Method): GET
• 響應格式 (Response): application/json
• CORS 支援: Access-Control-Allow-Origin: * (允許所有前端直接調用)
• 快取策略: 邊緣節點快取 30 分鐘 (max-age=1800)

---

2. 核心邏輯與優先級 (Core Logic)

在調用 API 時，系統會依照以下優先級順序處理參數：

1. 第一優先級：精確鎖定 (caseID)

• 若請求中包含 caseID，系統將忽略所有其他參數 (如 page, limit, year 等)，僅回傳該單一案件。

2. 第二優先級：條件篩選 (Filters)

• 若無 caseID，系統會執行篩選。
• 所有條件均為 AND (且) 邏輯。
• Unit 與 subUnit 採用 模糊匹配 (Partial Match)。
• minAge/maxAge 會自動剔除無效年齡數據。

3. 第三優先級：分頁與排序 (Pagination & Sorting)

• 篩選完畢後，執行排序 (order) 和分頁裁切 (page, limit)。

---

3. 請求參數詳解 (Request Parameters)

所有參數均為 可選 (Optional)。 注意：篩選參數名稱必須與數據欄位名稱完全一致 (區分大小寫)。

3.1 系統控制參數 (System Control)

參數名稱	類型	預設值	說明
caseID	String	-	唯一個案編號 (如 2025011002)。排他性參數。
page	Integer	1	頁碼。
limit	Integer	-	每頁筆數。若未提供，則回傳所有符合條件的記錄 (不分頁)。
order	String	-	排序方式 (依 caseID)。 • asc: 升序 (舊 → 新) • desc: 降序 (新 → 舊)

3.2 數值與日期範圍 (Ranges)

參數名稱	格式/類型	範例	詳細說明
startDate	YYYY-MM-DD	2024-01-01	篩選發現日期 (caseDate) 大於或等於 此日期。
endDate	YYYY-MM-DD	2024-12-31	篩選發現日期 (caseDate) 小於或等於 此日期。
minAge	Integer	18	篩選年齡 (Age) 大於或等於 此值。 ⚠️ 自動過濾：使用此參數時， 會自動剔除年齡為「不詳」或非數字的記錄。
maxAge	Integer	60	篩選年齡 (Age) 小於或等於 此值。 ⚠️ 自動過濾：同上。
year	Integer	2024	輔助參數，比對 caseDate 的年份。

3.3 模糊搜尋 (Fuzzy Search)

此類參數支援部份匹配，只要包含關鍵字即符合條件。

參數名稱	對應欄位	範例	說明
Unit	Unit	彌敦道, 花園	搜尋屋苑、街道或大廈名稱。 輸入 彌敦道 可匹配 彌敦道、彌敦道1號、彌敦道700號。
subUnit	subUnit	3座, 後巷	搜尋詳細位置 (座數、樓層等)。

3.4 精確內容篩選 (Exact Match)

需完全匹配資料庫中的內容，參數名稱需與欄位名稱完全一致。

參數名稱	對應欄位	說明	範例
newsDate	newsDate	報道日期	2024-05-20
caseDate	caseDate	發現日期	2024-05-20
Area	Area	區域	新界
District	District	18區	屯門區 (必須含「區」字)
subDistrict	subDistrict	分區	馬鞍山
House	House	房屋類型	公共屋邨
Gender	Gender	性別	男, 女
Age	Age	年齡 (字串)	25 (範圍查詢請用 minAge/maxAge)
State	State	綜合狀態	身亡

3.5 狀態篩選 (Boolean-like)

參數名稱	對應欄位	選項	說明
suicideNote	suicideNote	有, 沒有	現場有沒有遺書
Hospitalized	Hospitalized	有, 沒有	事主有沒有送院
mental_illness	mental_illness	有, 沒有	精神病患記錄
emotional_illness	emotional_illness	有, 沒有	情緒病患記錄
missingRecord	missingRecord	有, 沒有	失蹤記錄
newsHelp	newsHelp	有, 沒有	報道有沒有求助熱線

3.6 關鍵字邏輯篩選 (Complex Logic)

參數名稱	邏輯	說明
reason	OR (或)	自動搜尋 reason1, reason2, reason3。 範例：感情, 財政。
type	OR (或)	自動搜尋 type1, type2, type3。 範例：跳落, 燒炭。

---

4. 回傳數據結構 (Response Schema)

4.1 根目錄結構 (Root Object)

{
  "meta": {
    "totalRecords": 100,      // 符合篩選條件的總記錄數
    "totalPages": 5,          // 總頁數 (僅在設定 limit 時出現)
    "currentPage": 1,         // 當前頁碼 (僅在設定 limit 時出現)
    "pageSize": 20,           // 每頁筆數 (僅在設定 limit 時出現)
    "mode": "all_records"     // 若無 limit，則顯示此模式
  },
  "records": [
    // 案件列表 (Array)，詳見下方數據字典
    { ... },
    { ... }
  ]
}

4.2 數據字典 (Data Dictionary)

此表列出 records 物件中的所有欄位及其完整選項 (Enum)。請注意，這些欄位名稱即為上述的請求參數名稱。

欄位名稱 (Key)	類型	說明	選項與格式 (完整列表)
caseID	String	唯一個案編號	格式：YYYYMMDDXX
newsDate	String	報道日期	格式：YYYY-MM-DD
newsTime	String	報道時間	格式：HH:MM
newsHelp	String	有沒有求助熱線	有, 沒有
newsURL	String	新聞網址	URL
caseDate	String	發現日期	格式：YYYY-MM-DD
caseTime	String	發現時間	格式：HH:MM
Area	String	區域	港島, 九龍, 新界
District	String	地區 (18區)	中西區, 灣仔區, 東區, 南區, 油尖旺區, 深水埗區, 九龍城區, 黃大仙區, 觀塘區, 葵青區, 荃灣區, 屯門區, 元朗區, 北區, 大埔區, 沙田區, 西貢區, 離島區
subDistrict	String	分區	(自定義文字，如 尖沙咀, 馬鞍山)
Unit	String	街道 / 屋邨 / 建築	(自定義文字，如 怡樂花園, 彌敦道)
subUnit	String	門牌 / 樓宇 / 地點	(自定義文字，如 3座, 後巷)
Latitude	String	緯度	WGS84 格式
Longitude	String	經度	WGS84 格式
House	String	房屋類型	公共屋邨, 居屋, 豪宅, 私人屋苑, 洋樓, 唐樓, 村屋, 服務式住宅, 非住宅
firstName	String	事主姓氏	(自定義文字，若未知則為 不詳)
Gender	String	性別	男, 女
Age	String	年齡	數字字串 (如 16) 或 不詳
Hospitalized	String	有沒有送院	有, 沒有
State	String	綜合狀態	身亡, 昏迷, 紊亂, 迷糊, 清醒, 不詳
suicideNote	String	有沒有遺書	有, 沒有
mental_illness	String	精神病記錄	有, 沒有
emotional_illness	String	情緒病記錄	有, 沒有
missingRecord	String	失蹤記錄	有, 沒有
reason1 reason2 reason3	String	懷疑原因	感情, 工作, 生活, 健康, 家庭, 學業, 財政, 要脅, 畏罪, 酒精, 藥品, 不詳
type1 type2 type3	String	個案類別	跳落, 淹溺, 燒炭, 自縊, 氣體, 窒息, 交通, 出血, 藥品, 自焚, 液體, 槍械, 不詳

---

5. 實用查詢範例 (Usage Examples)

1. 模糊搜尋地址 (注意參數大小寫) 搜尋所有發生在「彌敦道」的案件：
https://hkspd.siuyeong.com/api_v2?Unit=彌敦道

2. 日期範圍查詢 搜尋 2024 年上半年發生的案件：
https://hkspd.siuyeong.com/api_v2?startDate=2024-01-01&endDate=2024-06-30

3. 年齡與地區篩選 搜尋發生在「新界」，且事主年齡為「65歲或以上」的案件：
https://hkspd.siuyeong.com/api_v2?Area=新界&minAge=65

4. 複雜條件 (房屋類型+原因+狀態) 搜尋發生在「公共屋邨」，原因涉及「健康」，且最終狀態為「身亡」的案件：
https://hkspd.siuyeong.com/api_v2?House=公共屋邨&reason=健康&State=身亡

5. 完整分頁 搜尋「男性」案件，每頁顯示 50 筆，查看第 2 頁，按最新排序：
https://hkspd.siuyeong.com/api_v2?Gender=男&page=2&limit=50&order=desc

6. 精神病與情緒病篩選 搜尋有精神病及有情緒病記錄的案件：
https://hkspd.siuyeong.com/api_v2?mental_illness=有&emotional_illness=有

---

6. JSON 回傳範例

以下為呼叫 https://hkspd.siuyeong.com/api_v2?limit=1 時的標準 JSON 回傳格式：

{
  "meta": {
    "totalRecords": 7392,
    "totalPages": 7392,
    "currentPage": 1,
    "pageSize": 1
  },
  "records": [
    {
      "caseID": "2026011501",
      "newsDate": "2026-01-15",
      "newsTime": "07:35",
      "newsHelp": "有",
      "newsURL": "https://siuyeo.ng/hkspd202601150701",
      "caseDate": "2026-01-15",
      "caseTime": "07:01",
      "Area": "九龍",
      "District": "九龍城區",
      "subDistrict": "紅磡",
      "Unit": "黃埔花園百合苑",
      "subUnit": "7座",
      "Latitude": "22.3026073684034",
      "Longitude": "114.190030959299",
      "House": "私人屋苑",
      "firstName": "胡",
      "Gender": "男",
      "Age": "25",
      "Hospitalized": "沒有",
      "State": "身亡",
      "suicideNote": "沒有",
      "mental_illness": "沒有",
      "emotional_illness": "沒有",
      "missingRecord": "沒有",
      "reason1": "生活",
      "type1": "跳落"
    }
  ]
}