CJK Calendar Converter

Convert between East Asian lunisolar calendars (Chinese, Japanese, Korean, Vietnamese) and Gregorian/Julian dates. All conversions run locally against a SQLite database — no network calls after setup.

When to Use

• Converting a CJK era date to Gregorian (e.g., 崇禎三年四月初三 → 1630-05-14)
• Converting a Gregorian date to concurrent CJK era dates
• Looking up era metadata (date ranges, dynasties, emperors)
• Computing sexagenary cycle (干支) for a given date
• Working with Julian Day Numbers (JDN)
• Japanese era shorthand for lunisolar Meiji dates (M1.9.8 to M5.12.2, e.g. M2.1.1)

Setup

Download the SQLite database (~14 MB) on first use:

python3 scripts/calendar_converter.py setup

This downloads calendar.db into the scripts/ directory. Only needed once.

To keep the database somewhere else, add --db PATH to any command (also to setup):

python3 scripts/calendar_converter.py setup --db ~/data/calendar.db
python3 scripts/calendar_converter.py convert "崇禎三年四月初三" --db ~/data/calendar.db

Quick Start

CJK Date → Gregorian

python3 scripts/calendar_converter.py convert "崇禎三年四月初三"
python3 scripts/calendar_converter.py convert "康熙六十一年十二月二十九日"
python3 scripts/calendar_converter.py convert "天保三年閏十一月十五日"
python3 scripts/calendar_converter.py convert "M2.1.1"
python3 scripts/calendar_converter.py convert "天保三年十一月初一" --country japanese

--country (chinese, japanese, korean or vietnamese) keeps only that calendar's matches. Unknown options and extra arguments are errors.

Gregorian → CJK Dates

python3 scripts/calendar_converter.py gregorian 1644 4 25
python3 scripts/calendar_converter.py gregorian 1832 11 22 --country japanese

1644-04-25 (Gregorian) is 崇禎十七年三月十九日, the day Beijing fell. "三月十九日" is the lunar date, not March 19.

JDN → All Calendars

python3 scripts/calendar_converter.py jdn 2299161

Search Eras

python3 scripts/calendar_converter.py eras --name 康熙
python3 scripts/calendar_converter.py eras --dynasty 明 --country chinese
python3 scripts/calendar_converter.py eras --country japanese

Supported Input Formats

Output Format

All commands output JSON. Example for convert:

[
  {
    "input_era": {
      "era_name": "崇禎",
      "era_id": 650,
      "emperor_name": "思宗",
      "dynasty_name": "明",
      "country": "chinese",
      "year_in_era": 3,
      "month": 4,
      "month_name": "四",
      "is_leap_month": false,
      "day": 3
    },
    "jdn": 2316539,
    "gregorian": "1630-05-14",
    "julian": null,
    "ganzhi": { "year": "庚午", "month": "辛巳", "day": "壬子" },
    "all_cjk_dates": [
      { "era_name": "崇禎", "country": "chinese", "year_in_era": 3, ... },
      { "era_name": "天聰", "country": "chinese", "year_in_era": 4, ... },
      { "era_name": "寛永", "country": "japanese", "year_in_era": 7, ... }
    ]
  }
]

• In convert, ganzhi.year and ganzhi.month come from the calendar you entered. Months can differ between calendars: Japanese 天保3年十一月 (month 壬子) is Chinese 道光12年十月 (month 辛亥). In jdn and gregorian, they come from the first row (Chinese first), or from the --country you give. A leap month has no month 干支, so month is empty.
• continued_use: true means the era had officially ended, but the database keeps counting it for later use. Example: 崇禎 goes on after 崇禎十七年三月十九日 (1644-04-25) up to year 268 (1895), because Ming loyalists and Joseon Korea kept using it. Such rows are still labelled chinese / 明. convert adds a note for them.
• julian is filled only for dates before the Gregorian reform (JDN < 2299161, i.e. before 1582-10-15); otherwise it is null.
• Years use astronomical numbering: 0000 = 1 BCE, -0001 = 2 BCE.
• The gregorian command takes a proleptic Gregorian date. For a Western date before 1582 written in the Julian calendar, convert it to JDN first and use the jdn command.

Key Concepts

Julian Day Number (JDN)

JDN is the universal pivot for all conversions. It's an integer day count from noon GMT, January 1, 4713 BCE (Julian calendar). Every lunisolar month record in the database stores its first_jdn and last_jdn.

Sexagenary Cycle (干支)

The 60-unit cycle combines 10 Heavenly Stems (天干: 甲乙丙丁戊己庚辛壬癸) with 12 Earthly Branches (地支: 子丑寅卯辰巳午未申酉戌亥). Used for years, months, and days.

• Day ganzhi: (JDN + 49) mod 60 gives the cycle index
• Month ganzhi: Derived from the year's Heavenly Stem via the Five Tigers formula (五虎遁)
• Year ganzhi: Stored in the database for each lunar month record

Ambiguous Era Names

The same era name can appear in different dynasties or countries (e.g., 建武 was used by both Han and Japanese emperors). When results are ambiguous, the converter returns all matches. Use --country to filter. Example: 天保三年 alone gives 38 months across 北齊, 西梁 and Japan; with --country japanese it gives 13.

Era names in the database use traditional characters (Japanese eras use Japanese forms, e.g. 寛永). Simplified names such as 万历 or 光绪 are converted for you. If a name is still not found, check it with eras --name.

Coverage

Total: 1,637 eras, 131,808 lunar month records.

Note: Japanese dates after Meiji 5 (1872) are not in the database because Japan adopted the Gregorian calendar in 1873. Japanese shorthand (M/T/S/H/R) only works for lunisolar-era dates, so T/S/H/R inputs return "No matching dates found".

Using in Python

Import the script directly for programmatic use:

import sys
sys.path.insert(0, "scripts")
from calendar_converter import (
    get_connection, parse_cjk_date, convert_cjk_to_jdn,
    convert_jdn, gregorian_to_jdn, get_era_metadata,
)

conn = get_connection()  # or get_connection(Path("~/data/calendar.db").expanduser())

# CJK → Gregorian
parsed = parse_cjk_date("康熙六十一年十二月二十九日")
results = convert_cjk_to_jdn(conn, parsed)
for jdn, era_info in results:
    conversion = convert_jdn(conn, jdn, era_id=era_info.era_id)  # 干支 of this calendar
    print(f"{era_info.era_name} → {conversion.gregorian}")

# Only Japanese dates: convert_cjk_to_jdn(conn, parsed, country="japanese")

# Gregorian → CJK
jdn = gregorian_to_jdn(1644, 4, 25)
conversion = convert_jdn(conn, jdn)
for cjk in conversion.cjk_dates:
    print(f"{cjk.era_name}{cjk.year_in_era}年{cjk.month_name}月{cjk.day}日 ({cjk.country})")

Database Schema

See references/database_schema.md for the full schema and query guide.

Resources

• scripts/calendar_converter.py — Standalone converter (Python 3.10+, zero dependencies)
• references/database_schema.md — SQLite schema and query patterns
• tests/test_calendar_converter.py — offline tests (build a small fixture database; run python3 -m unittest discover -s tests)
• Source data: DILA Authority Database

Inside the Ming research suite

When working in ming-qing-research-suite, its sino-authorities MCP server reads the same database and is the preferred route for converting era dates to JDN there. Use this skill for direct conversions, era lists, and raw SQL on calendar.db.

Feedback and Citation

Report a problem. This skill is part of the public repository 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 "cjk-calendar"
3. File it: gh issue create --repo kltng/humanities-skills --label bug --title "[cjk-calendar] <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: cjk-calendar (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.