Quick Start

Your first dynasty lookup in five minutes.

1. Install

git clone https://github.com/SongshGeoLab/chinese_history_toolkits.git
cd chinese_history_toolkits

# uv (recommended)
uv sync --all-extras

# or pip
pip install pandas

pandas is the only runtime dependency. The data ships with the package, so no network call is needed at runtime.

2. Your first lookup

import chhiskit

# By 年号 (reign era) — the default level
chhiskit.get_age_from_cultural_period("康熙")
# → (1662.0, 1722.0)

The result is (begin_year, end_year) in AD/BCE form (BCE is negative).

3. Choose the right level

# Reign-era query (single 年号)
chhiskit.get_age_from_cultural_period("贞观", level="period")
# → (627.0, 649.0)

# Dynasty-level query
chhiskit.get_age_from_cultural_period("唐", level="dynasty")
# → (618.0, 907.0)

# Meta-epoch query (汉, 三国, 五代, 上古, 新石器, ...)
chhiskit.get_age_from_cultural_period("三国", level="epoch")
# → (220.0, 280.0)

Three levels, one function

Levels are not strictly nested — period matches by reignTitle, dynasty by the literal dynasty column, epoch by the curated EPOCH_MAP. Pick the one whose semantics match your input.

4. Reverse lookup: what was happening in year X?

import chhiskit

matches = chhiskit.get_cultural_periods_from_year(250)
for m in matches:
    print(m.dynasty_id, m.reignTitle, m.beginYear, m.endYear)
# 三国        220.0  280.0
# 吴   赤乌  238.0  251.0
# 蜀   延熙  238.0  257.0
# 魏   嘉平  249.0  254.0

Multiple parallel polities are normal — 三国, 南北朝, 五代, 隋末唐初 all routinely overlap.

5. Need foreign names?

ALIASES = {
    "新石器": {"Neolithic", "Neo"},
    "唐":   {"Tang"},
    "康熙": {"Kangxi"},
}

chhiskit.get_age_from_cultural_period("Tang", level="dynasty", aliases=ALIASES)
# → (618.0, 907.0)

See the API Reference for full parameter behavior, BP-mode conversion, custom timetables, and error semantics.