kltng/cbdb-api

CBDB API

Query the China Biographical Database (~500K historical Chinese figures, 7th c. BCE–19th c. CE).

Critical: Things Claude Won't Know Without This Skill

API endpoint:

https://cbdb.fas.harvard.edu/cbdbapi/person.php

Response structure is deeply nested:

response["Package"]["PersonAuthority"]["PersonInfo"]["Person"]

The Person object contains: BasicInfo, AltNameInfo, AddrInfo, EntryInfo, PostingInfo, SocialAssocInfo, KinshipInfo.

Encoding: Pass Chinese characters as UTF-8 directly — do not URL-encode into hex.

Python Script

Use scripts/cbdb_api.py for programmatic access (zero dependencies):

from scripts.cbdb_api import CBDBAPI
api = CBDBAPI()

# By name (Chinese or Pinyin)
person = api.query_by_name("蘇軾")
person = api.query_by_name("Wang Anshi")

# By ID (most precise)
person = api.query_by_id(1762)

# Extract structured data
basic = api.get_basic_info(person)      # name, dates, dynasty
postings = api.get_postings(person)     # official positions
assocs = api.get_social_associations(person)  # social network
kinship = api.get_kinship(person)       # family relations
alt_names = api.get_alt_names(person)   # courtesy name, pen name, etc.

# Formatted summary
print(api.summarize(person))

The script handles rate limiting, retries, and the nested JSON navigation automatically.

Quick Reference

Query by Chinese name:

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

Query by Pinyin: (URL-encode spaces only)

https://cbdb.fas.harvard.edu/cbdbapi/person.php?name=Wang%20Anshi&o=json

Query by ID: (most precise)

https://cbdb.fas.harvard.edu/cbdbapi/person.php?id=1762&o=json

Priority: ID > Chinese characters > Pinyin (Pinyin may return multiple matches).

Handling Results

Multiple results from Pinyin queries: Check dynasty, dates, or other context to identify the correct person. If ambiguous, present options to the user.

Error response:

{"error": {"code": 404, "message": "Person not found."}}

Try alternative name forms (Chinese vs Pinyin), check spelling, or try courtesy names (字, 號).

BasicInfo fields: PersonId, EngName, ChName, IndexYear, Gender, YearBirth, YearDeath, Dynasty, Notes

Related Skills

• chgis-tgaz: Look up birthplaces or associated locations from CBDB's AddrInfo in the CHGIS Temporal Gazetteer
• wikidata-search: Cross-reference CBDB figures with Wikidata for external identifiers (VIAF, LoC, etc.)

Resources

• references/api_reference.md — Complete endpoint specs, all parameters, response structure details
• scripts/cbdb_api.py — Python client with rate limiting and structured data extraction