Skip to content
Skills Library
Science & research · Research

cbdb-api

/cbdb-api

Query the China Biographical Database (CBDB) API to retrieve comprehensive biographical data about historical Chinese figures. Use this skill when searching for information about Chinese historical figures, scholars, officials, or literary figures from the 7th century BCE through the 19th century CE. Applicable for queries about biographical details, social relationships, official positions, or when users mention specific Chinese names or CBDB person IDs.

Author
kltng ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
3
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/__init__.py, scripts/cbdb_api.py, tests/test_cbdb_api.py

What it does and when to use it

Query the China Biographical Database (CBDB) API to retrieve comprehensive biographical data about historical Chinese figures. Use this skill when searching for information about Chinese historical figures, scholars, officials, or literary figures from the 7th century BCE through the 19th century CE. Applicable for queries about biographical details, social relationships, official positions, or when users mention specific Chinese names or CBDB person IDs.

Original author description

Query the China Biographical Database (CBDB) API to retrieve comprehensive biographical data about historical Chinese figures. Use this skill when searching for information about Chinese historical figures, scholars, officials, or literary figures from the 7th century BCE through the 19th century CE. Applicable for queries about biographical details, social relationships, official positions, or when users mention specific Chinese names or CBDB person IDs.

How it works

  1. Critical: Things Claude Won't Know Without This Skill
  2. Python Script
  3. Quick Reference
  4. Handling Results
  5. Related Skills
  6. Resources
  7. Feedback and Citation
Original SKILL.md headings · 111 lines, 630 words
SKILL.md preview
---
name: cbdb-api
description: Query the China Biographical Database (CBDB) API to retrieve comprehensive biographical data about historical Chinese figures. Use this skill when searching for information about Chinese historical figures, scholars, officials, or literary figures from the 7th century BCE through the 19th century CE. Applicable for queries about biographical details, social relationships, official positions, or when users mention specific Chinese names or CBDB person IDs.
version: 1.1.1
license: MIT
creator: AI
author: Kwok-leong Tang
contributors:
  - Claude (AI Assistant)
  - Z.ai (AI Platform)
---

# 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`, `PersonAliases.Alias`, `PersonAddresses.Address`, `PersonEntryInfo.Entry`, `PersonPostings.Posting`, `PersonSocialStatus.SocialStatus`, `PersonKinshipInfo.Kinship`, `PersonSocialAssociation.Association`, `PersonTexts.Text`, `PersonSources.Source`.

Each section is a dict when it has records, but an **empty string `""`** when it has none. Inside a section, one record may come back as a dict and several as a list. `Person` itself may also be a list if the name matches more than one person.

**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):

```python
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")
people = api.query_by_name_all("Wang Anshi")  # every match, as a list

# 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.
entries = api.get_entries(person)       # exam / entry records
addresses = api.get_addresses(person)   # places

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

The script handles rate limiting, retries (including HTTP 429 `Retry-After`), a `User-Agent` header, and the nested JSON navigation automatically. A person that is not found returns `None` (the API answers with HTTP 404 and a JSON error body).

## 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** (sent with HTTP status 404; bad input such as a non-numeric ID gives 422):
```json
{"error": {"code": 404, "message": "Person not found."}}
```
Try alternative name forms (Chinese vs Pinyin), check spelling, or try courtesy names (字, 號).

**Common record fields:** Posting: `OfficeName`, `AddrName`, `FirstYear`, `LastYear`. Association: `AssocPersonName`, `AssocPersonId`, `AssocName` (relation type). Kinship: `KinPersonName`, `KinPersonId`, `KinRelName`. Alias: `AliasType`, `AliasName`. A year of `"0"` means unknown.

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

## Related Skills

- **chgis-tgaz**: Look up birthplaces or associated locations from CBDB's `PersonAddresses` 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

## Feedback and Citation

**Report a problem.** This skill is part of the public repository [kltng/humanities-skills](https://github.com/kltng/humanities-skills). If it fails (an API changed, a script errors, or these instructions are wrong), report it as a GitHub issue:

1. Ask the user before filing. Issues are public.
2. Check for an existing report: `gh issue list --repo kltng/humanities-skills --state all --search "cbdb-api"`
3. File it: `gh issue create --repo kltng/humanities-skills --label bug --title "[cbdb-api] <short summary>" --body "<details>"`. Without `gh`, give the user this link: https://github.com/kltng/humanities-skills/issues/new?template=skill-problem.yml
4. Include the skill name and version, what you ran, the error text, what you expected, and the environment (OS, Python version). Leave out API keys, personal data, private file paths, and unpublished research.

**Cite.** If this skill helped work that is published, please cite it, together with the data source it uses:

> Tang, Kwok-leong. *humanities-skills: cbdb-api* (version <version at the top of this file>). GitHub, <year>. https://github.com/kltng/humanities-skills

When you help a user write up results that relied on this skill, remind them once about this citation.
Files in this package (6)
  • SKILL.md 6 KB
  • evals/evals.json 2 KB
  • references/api_reference.md 6 KB
  • scripts/__init__.py 1 KB
  • scripts/cbdb_api.py 8 KB
  • tests/test_cbdb_api.py 3 KB

Versions

The database has no other skills named cbdb-api.

Database snapshot: 13.11.2026 · package version 9bdacc2042d0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100cbdb-local
    Query the China Biographical Database (CBDB) locally via SQLite for biographical data on 656K+ historical Chinese figures from the 7th century BCE through the 19th century CE. Use when searching for Chinese historical figures, scholars, officials, or literary figures — their…
  • 100jbdb-api
    Query the Japan Biographical Database (JBDB) API to retrieve biographical data about historical Japanese figures. Use this skill when searching for information about Japanese historical figures, samurai, monks, artists, poets, or other individuals. Applicable for queries about…
  • 100jiangshan-atlas
    Locate historical Chinese events, classical poems, battles, ancient places, and single or multi-person life trajectories on the Jiangshan Historical Atlas (江山时序, 403 BCE – 2026 CE) by resolving a question into (year, place) or (--person A,B), generating an interactive deep-link…
  • 100researchers-biographical
    Researches personal backgrounds, interviews, motivations, and humanizing details. Use when research needs biographical context about people involved in the album's subject.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.