kltng/cjk-calendar

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 (M45.7.30, H26.6.8)

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.

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 "M1.1.1"

Gregorian → CJK Dates

python3 scripts/calendar_converter.py gregorian 1644 3 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

| Format | Example | Notes | |---|---|---| | Chinese numerals | 崇禎三年四月初三 | Standard CJK date | | Leap month | 天保三年閏九月十五日 | 閏 prefix marks leap | | 元年 (year 1) | 康熙元年正月初一 | 元 = 1, 正 = month 1 | | 廿/卅 shorthand | 光緒廿八年三月卅日 | 廿 = 20, 卅 = 30 | | Arabic numerals | 康熙61年12月29日 | Mixed format | | Japanese shorthand | M1.1.1 | M/T/S/H/R for eras (lunisolar years only) | | Ganzhi year | 嘉慶甲午年三月初五 | Sexagenary year cycle | | Full ganzhi | 嘉慶甲午年丁亥月丙子日 | Year + month + day ganzhi |

Output Format

All commands output JSON. Example for convert:

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

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.

Coverage

| Region | Coverage | Era Count | |---|---|---| | Chinese | ~220 BCE – 1912 CE | ~900 eras | | Japanese | 645 CE – 1945 CE | ~250 eras | | Korean | Various periods | ~200 eras | | Vietnamese | Various periods | ~200 eras |

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.

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()

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

# Gregorian → CJK
jdn = gregorian_to_jdn(1644, 3, 19)
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
• Source data: DILA Authority Database