API 使用指南

基礎資訊

基礎 URL	`https://dic.cantonese.top/api`
返回格式	JSON（UTF-8，中文不轉義）
CORS	`Access-Control-Allow-Origin: *`
速率限制	暫無，請合理使用

1. 漢字查詢

查詢單個漢字的讀音詳情，包括在各典籍中的讀音、異讀分類。

GET /api/char.php?char=粵

參數

參數	類型	必填	説明
char	string	是	單個漢字，只取第一個字符

響應示例

{
  "code": 0,
  "data": {
    "char": "粵",
    "stroke_count": 13,
    "radical": "米",
    "unicode": "U+7CB5",
    "jyutpings": ["jyut6", "jyut9"],
    "dictionaries": [{
      "year": 1856,
      "name": "英華分韻撮要",
      "readings": [{
        "jyutping": "jyut6",
        "initial": "j",
        "final": "yut",
        "tone": 9,
        "reading_mark": "",
        "definition": "廣東簡稱",
        "remark": ""
      }]
    }]
  }
}

2. 搜索

搜索漢字或拼音，支援分頁。自動識別查詢類型（含字母則為拼音搜索）。

GET /api/search.php?q={關鍵詞}&page=1&per_page=30

參數

參數	類型	必填	説明
q	string	是（或 dict）	搜索關鍵詞（漢字或粵拼）
dict	int	否	按字典 ID 瀏覽收錄漢字
page	int	否	頁碼，預設 1
per_page	int	否	每頁條數，預設 30，最大 100

搜索類型説明

示例	説明
`q=粵語`	漢字搜索（查詢「粵」「語」兩字）
`q=jyut6`	粵拼精確搜索
`q=jyut*`	通配符搜索（`*` 匹配任意字符）
`q=jyut6:fan1`	多音搜索（冒號分隔，查找同時有兩個讀音的字）
`q=[jyut6,fan1]`	方括號條件（匹配其中任一讀音）
`dict=3`	瀏覽第 3 號字典的所有收錄漢字

3. 字典列表

獲取所有收錄典籍的列表。

GET /api/dict.php

無需參數。

4. 拼音篩選

按聲母、韻母、聲調篩選漢字。

GET /api/phonetic.php?initial=b&final=aa&tone=1

參數

參數	類型	必填	説明
initial	string	否	聲母，如 b、p、m、f、gw、kw 等
final	string	否	韻母，如 aa、aai、ing、yut 等
tone	int	否	聲調（1-6），自動匹配對應入聲（7-9）
page	int	否	頁碼，預設 1
per_page	int	否	每頁條數，預設 30，最大 100

至少需要指定 initial、final 或 tone 其中一個參數。

統一響應格式

// 成功
{ "code": 0, "data": [...], "total": 123, "page": 1, "per_page": 30 }

// 失敗
{ "code": 400, "message": "缺少參數" }
{ "code": 404, "message": "未收錄" }

code 為 0 表示成功，其他值為錯誤代碼。

調用示例

// JavaScript (fetch)
fetch('https://dic.cantonese.top/api/char.php?char=粵')
  .then(res => res.json())
  .then(data => console.log(data.data.jyutpings));

// Python (requests)
import requests
r = requests.get('https://dic.cantonese.top/api/search.php', params={'q': 'jyut6', 'page': 1})
print(r.json())

// curl
curl "https://dic.cantonese.top/api/phonetic.php?initial=b&final=aa&tone=1"