Documentation

Quickstart

Five lines to get from a UTC timestamp to seven synchronized calendars.

1. Install

npm install @unified-calendar/core

2. Decode

Import the decoder and pass an ISO 8601 UTC string. The return value contains one field per calendar system, plus the canonical UCP string.

const { decodeUCP } = require('@unified-calendar/core');

const data = decodeUCP("2026-03-21T14:30:00Z");

What comes back

{
  ucpString: 'UE-12026 :: 03.21-04 :: 02.03.03 H10.02 (U) [Jia-Wu] T14:30:00Z',
  gregorian: 'Year 2026, Month 3, Day 21',
  xia: 'Year 丙午, Month 辛卯, Day Jia-Wu (Solar Term: 春分)',
  chinese: 'Year 4724, M: 2, D: 3',
  hindu: 'Amanta Month 1, Tithi 3, Nakshatra 3',
  buddhist: 'Year BE 2569, Lunar Month 2, Day 3',
  saka: 'Year Saka 1947, Month 12, Day 30',
  islamic: 'Year 1447 AH, Shawwal (M: 10), Day 2'
}
Output for 2026-03-21T14:30:00Z

3. Read a field

console.log(data.saka);
//> Year Saka 1947, Month 12, Day 30

Notes

  • The package is CommonJS; use require() in Node.js or import it from an ESM wrapper.
  • All calculations are geocentric and performed in UTC. Convert local birth times before calling decodeUCP().
  • astronomy-engine and lunar-javascript are installed automatically as dependencies.
  • The library is MIT licensed. The hosted API is separate and not yet available.

Next

The seven calendar systemsGenerate a full-year almanac