Skip to content

Chinese History Toolkits

Map any year to its Chinese dynasty / reign-era / epoch — and back. Built on the Shanghai Library open data, with a transparent cleaning pipeline so every change traces back to the source.

What you get

  • 🏛️ Two-way lookup — name → (begin, end) years; year → list of parallel polities.
  • 🪨 Full timeline — 旧石器 / 新石器 prehistoric brackets through 清.
  • 📚 Selectable chronology — 上古 dating is contested scholarship; pick the source you trust.
  • 🧭 Disambiguated — reused names resolve correctly (夏(窦建德) ≠ 上古 夏); an ambiguous 年号 raises rather than guessing.
  • 🌐 Alias-friendly — pass an aliases map so Neolithic / Kangxi / Tang resolve correctly.

Two-minute taste

import chhiskit

# Name → years
chhiskit.get_age_from_cultural_period("康熙", level="period")
# → (1662.0, 1722.0)

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

chhiskit.get_age_from_cultural_period("新石器", level="epoch")
# → (-10000.0, -2070.0)

# Year → all matching polities (parallel during 三国 / 隋末 / etc.)
[m.dynasty_id for m in chhiskit.get_cultural_periods_from_year(250)]
# → ['三国', '吴', '蜀', '魏']

[m.dynasty_id for m in chhiskit.get_cultural_periods_from_year(619)]
# → ['唐', '夏(窦建德)', '梁', '楚', ...]   # 隋末 — many parallel polities

# BP convention (radiocarbon, 1950 reference)
chhiskit.get_age_from_cultural_period("商", level="dynasty", anno_domini=False)
# → (3550.0, 2996.0)   # older first, in BP

# Foreign-language aliases
chhiskit.get_age_from_cultural_period(
    "Neolithic", level="epoch",
    aliases={"新石器": {"Neolithic", "Neo"}},
)
# → (-10000.0, -2070.0)

Where to next

Data attribution

Source Used for
上海图书馆开放数据平台 Base table — 朝代 / 年号 / 帝王
夏商周断代工程 (2000) 上古 chronology (source="xsz", default)
万国鼎《中国历史纪年表》(中华书局, 1956) 国号 / 朝代 spans (source="wgd")

Data ships with the package — no network call at runtime.