API 使用說明

API 使用與格式說明文檔

1. 基本結構 (Endpoints)

請求的基礎 URL 格式如下：

  • 基礎接口： https://hkspd.siuyeong.com/api

  • 分頁與排序： https://hkspd.siuyeong.com/api?page=<page>&limit=<limit>&order=<order>

  • 指定個案查詢： https://hkspd.siuyeong.com/api?caseID=<caseID>

  • CORS 問題： https://codetabs.com/cors-proxy/cors-proxy.html

2. 請求參數說明 (Parameters)

所有請求均使用 HTTP GET 方法。參數可透過 Query String 傳遞。

參數邏輯優先級 (Priority Logic)

注意：本 API 具有參數互斥邏輯。

  1. 系統優先檢查是否包含 caseID。
  2. 若 caseID 存在，將忽略 page, limit, order 參數，僅回傳單筆資料。
  3. 若 caseID 不存在，則根據 page, limit, order 執行分頁查詢。

?page=<page>

  • 功能：指定要獲取的頁碼。當沒有指定 caseID 時有效。
  • 預設值：如果未提供，則默認為 1。
  • 範例：?page=2 將返回第二頁的數據。

?limit=<limit>

  • 功能：指定每頁返回的記錄數。當沒有指定 caseID 時有效。
  • 預設值：如果未提供，則不進行分頁，返回所有記錄。
  • 範例：?limit=10 將每頁限制為 10 條記錄。

?order=<order>

  • 功能：指定返回記錄的排序方式。當沒有指定 caseID 時有效。
  • 可選值：
    • asc：按 caseID 升序排序。
    • desc：按 caseID 降序排序。
  • 範例：?order=asc 將返回按 caseID 升序排列的記錄。

?caseID=<caseID>

  • 功能：根據指定的 caseID 過濾返回的記錄。
  • 行為：如果提供了 caseID，只會返回唯一一項記錄，此時 page、limit 和 order 參數無效。
  • 範例：?caseID=2025011002 將僅返回 caseID 為 2025011002 的記錄。

3. 使用範例 (Usage Examples)

獲取第一頁的所有記錄：
https://hkspd.siuyeong.com/api

獲取第二頁的 10 條記錄：
https://hkspd.siuyeong.com/api?page=2&limit=10

獲取特定 caseID 的記錄（唯一一項）：
https://hkspd.siuyeong.com/api?caseID=2025011002

獲取特定 caseID 的記錄並指定排序（無效，因為只返回唯一一項）：
https://hkspd.siuyeong.com/api?caseID=2025011002&order=asc

獲取特定 caseID 的第一頁 5 條記錄，並按降序排序（無效，因為只返回唯一一項）：
https://hkspd.siuyeong.com/api?caseID=2025011002&page=1&limit=5&order=desc

4. 回傳結構說明 (Response Schema)

此 API 回傳有關案件的統計數據與詳細清單。

根目錄結構 (Root Object)

欄位名稱 類型 說明
totalRecords Number 總記錄筆數
totalPages Number 總頁數 (如有分頁)
currentPage Number 現時頁數 (如有分頁)
pageSize Number 每頁多少個案 (如有分頁)
records Array 案件記錄列表 (詳細欄位見下表)

案件記錄結構 (Record Object)

records 陣列中的每個物件包含以下欄位：

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

5. JSON 回傳範例

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

{
  "totalRecords": 7312,
  "totalPages": 7312,
  "currentPage": 1,
  "pageSize": 1,
  "records": [
    {
      "caseID": "2025121502",
      "newsDate": "2025-12-15",
      "newsTime": "17:21",
      "newsHelp": "有",
      "newsURL": "https://siuyeo.ng/hkspd202512151628",
      "caseDate": "2025-12-15",
      "caseTime": "16:28",
      "Area": "新界",
      "District": "屯門區",
      "subDistrict": "新墟",
      "Unit": "怡樂花園",
      "subUnit": "3座",
      "Latitude": "22.4047548579413",
      "Longitude": "113.981916227339",
      "House": "私人屋苑",
      "firstName": "不詳",
      "Gender": "男",
      "Age": "16",
      "Hospitalized": "有",
      "State": "身亡",
      "suicideNote": "沒有",
      "mental_illness": "沒有",
      "emotional_illness": "沒有",
      "missingRecord": "沒有",
      "reason1": "不詳",
      "type1": "跳落"
    }
  ]
}