CBDB API 使用說明

中國歷代人物傳記資料庫（CBDB）提供開放的 RESTful API， 允許開發者和研究者透過程式化方式查詢人物資料。 API 以 JSON 格式輸出，並提供豐富的人物傳記資訊， 包括基本資料、別名、地址、任官、親屬關係、社會關係、著述等。

The China Biographical Database (CBDB) provides an open RESTful API that allows developers and researchers to programmatically query biographical data. The API returns data in JSON format and provides comprehensive biographical information including basic details, aliases, addresses, postings, kinship relations, social associations, and texts.

支援的 HTTP 方法 HTTP Methods: GET

編碼 Encoding: UTF-8

參數 Parameter	類型 Type	必填 Required	說明 Description
id	integer	擇一 Either	人物 ID（c_personid） Person ID (c_personid)
name	string	擇一 Either	人物姓名（支援中文名、英文名、別名，最多返回 50 個候選人） Person name (supports Chinese name, English name, aliases; returns up to 50 candidates)
o 或 mode	string	選填 Optional	輸出格式：json 或不填（預設為可供閱覽的網頁） Output format: json or omit (defaults to HTML page for viewing)

1. 透過 ID 查詢 Query by ID

網頁版 HTML version:

GET https://cbdb.fas.harvard.edu/cbdbapi/person?id=21246

JSON 版 JSON version:

GET https://cbdb.fas.harvard.edu/cbdbapi/person?id=21246&mode=json

HTML JSON

2. 透過姓名查詢 Query by Name

網頁版 HTML version:

GET https://cbdb.fas.harvard.edu/cbdbapi/person?name=蘇軾

JSON 版 JSON version:

GET https://cbdb.fas.harvard.edu/cbdbapi/person?name=蘇軾&mode=json

HTML JSON

3. cURL 範例 cURL Example

curl -X GET "https://cbdb.fas.harvard.edu/cbdbapi/person?id=21246&mode=json" \
     -H "Accept: application/json"

4. Python 範例 Python Example

import requests

# 查詢蘇軾的資料
response = requests.get(
    'https://cbdb.fas.harvard.edu/cbdbapi/person',
    params={'id': 21246, 'mode': 'json'}
)

if response.status_code == 200:
    data = response.json()
    person = data['Package']['PersonAuthority']['PersonInfo']['Person']
    print(f"姓名: {person['BasicInfo']['ChName']}")
    print(f"ID: {person['BasicInfo']['PersonId']}")
else:
    print(f"錯誤: {response.status_code}")

5. JavaScript 範例 JavaScript Example

// 使用 Fetch API 查詢
fetch('https://cbdb.fas.harvard.edu/cbdbapi/person?id=21246&mode=json')
    .then(response => response.json())
    .then(data => {
        const person = data.Package.PersonAuthority.PersonInfo.Person;
        console.log('姓名:', person.BasicInfo.ChName);
        console.log('ID:', person.BasicInfo.PersonId);
    })
    .catch(error => console.error('錯誤:', error));

JSON 回應結構 JSON Response Structure

{
  "Package": {
    "PersonAuthority": {
      "PersonInfo": {
        "Person": {
          "BasicInfo": {
            "PersonId": "21246",
            "ChName": "蘇軾",
            "EngName": "Su Shi",
            "IndexYear": "1037",
            ...
          },
          "PersonSources": {
            "Source": [...]
          },
          "PersonAliases": {
            "Alias": [...]
          },
          "PersonAddresses": {
            "Address": [...]
          },
          "PersonEntryInfo": {
            "Entry": [...]
          },
          "PersonPostings": {
            "Posting": [...]
          },
          "PersonSocialStatus": {
            "SocialStatus": [...]
          },
          "PersonKinshipInfo": {
            "Kinship": [...]
          },
          "PersonSocialAssociation": {
            "Association": [...]
          },
          "PersonTexts": {
            "Text": [...]
          }
        }
      }
    }
  }
}

資料區塊說明 Data Sections

• BasicInfo: 基本資訊（姓名、生卒年、朝代、性別等）
  Basic information (name, birth/death years, dynasty, gender, etc.)
• PersonSources: 出處資料
  Source references
• PersonSourcesAs: 人名權威資料鏈接
  Name authority data links
• PersonAliases: 別名（字、號等）
  Aliases (courtesy names, art names, etc.)
• PersonAddresses: 地址資訊（籍貫、活動地等）
  Address information (native place, activity locations, etc.)
• PersonEntryInfo: 入仕資料（科舉等）
  Entry information (examinations, etc.)
• PersonPostings: 任官記錄
  Official posting records
• PersonSocialStatus: 社會區分（士人、宗室等）
  Social status (scholar, royal clan, etc.)
• PersonKinshipInfo: 親屬關係
  Kinship relations
• PersonSocialAssociation: 社會關係（師生、友人等）
  Social associations (teacher-student, friends, etc.)
• PersonTexts: 著述資料
  Text/authorship information

HTTP 狀態碼 HTTP Status Codes

狀態碼 Code	說明 Description
200	成功 Success
404	找不到指定的人物 Person not found
422	參數驗證失敗 Validation failed
500	伺服器內部錯誤 Internal server error

錯誤回應範例 Error Response Example

{
  "error": {
    "code": 404,
    "message": "找不到 ID 為 999999 的人物。",
    "details": []
  }
}

人物合併提示 Person Merge Hint

當查詢的人物 ID 已被合併到另一個 ID 時，錯誤回應會包含 merge_hint：
When querying a person ID that has been merged to another ID, the error response will include a merge_hint:

{
  "error": {
    "code": 404,
    "message": "找不到 ID 為 12345 的人物。",
    "merge_hint": {
      "merged_to_person_id": 67890,
      "reason": "重複人物合併"
    }
  }
}

• 單次姓名查詢最多返回 50 個候選人
  Name queries return up to 50 candidates per request
• 建議在應用程式中實作適當的快取機制以減少重複查詢
  Recommended to implement appropriate caching in your application to reduce duplicate queries
• 對於大量資料查詢需求，請考慮下載完整資料庫
  For bulk data queries, please consider downloading the complete database

1. 優先使用 ID 查詢：如果已知人物 ID，直接使用 ID 查詢效能最佳
   Prefer ID queries: If the person ID is known, direct ID queries have the best performance
2. 處理姓名查詢的多個結果：使用姓名查詢時，可能返回多個同名人物，需要額外邏輯選擇正確的人物
   Handle multiple name query results: Name queries may return multiple people with the same name, requiring additional logic to select the correct person
3. 實作錯誤處理：妥善處理 404 和其他錯誤狀態
   Implement error handling: Properly handle 404 and other error statuses
4. 快取結果：CBDB 資料更新頻率較低，建議快取查詢結果以提升應用效能
   Cache results: CBDB data updates infrequently; caching query results is recommended to improve application performance
5. 尊重授權條款：使用 API 資料時請遵守 CC BY-NC-SA 4.0 授權
   Respect the license: When using API data, please comply with the CC BY-NC-SA 4.0 license

CBDB API 提供的資料採用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) 授權。這表示您可以：

• 分享：以任何媒介或格式複製及散布本素材
• 修改：重混、轉換本素材、及依本素材建立新素材

但必須遵守以下條件：

• 姓名標示：您必須給予適當表彰、提供指向本授權條款的連結
• 非商業性：您不得將本素材進行商業目的之使用
• 相同方式分享：若您重混、轉換或依本素材建立新素材，您必須依本素材的授權條款來散布您的貢獻物

---

Data provided by the CBDB API is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) . This means you are free to:

• Share: Copy and redistribute the material in any medium or format
• Adapt: Remix, transform, and build upon the material

Under the following terms:

• Attribution: You must give appropriate credit and provide a link to the license
• NonCommercial: You may not use the material for commercial purposes
• ShareAlike: If you remix, transform, or build upon the material, you must distribute your contributions under the same license

專案網站 Project Website:
https://cbdb.hsites.harvard.edu/

資料庫入口 Database Portal:
https://input.cbdb.fas.harvard.edu/

技術問題 Technical Issues:
如遇到 API 技術問題，請透過專案網站聯繫我們。
For API technical issues, please contact us through the project website.