Developers

One timestamp. Seven calendars.

UCP is an open standard for keeping cultural calendars in sync without intercalation drift. The reference implementation is a Node.js library, MIT licensed and free forever.

View source on GitHubInstall from npm

Install

The engine ships as a Node.js package. Its two dependencies, astronomy-engine and lunar-javascript, install automatically.

npm install @unified-calendar/core

Decode a timestamp

decodeUCP() takes an ISO 8601 UTC string and returns every calendar system locked to that instant.

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

// One UTC instant, every calendar system.
const data = decodeUCP("2026-03-21T14:30:00Z");

console.log(data.xia);
//> Year 丙午, Month 辛卯, Day Jia-Wu (Solar Term: 春分)

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'
}

The seven systems

Every system below is derived from the same astronomical instant, not from a lookup table of offsets.

  • GregorianCivil standard
  • Xia (Hsia)Solar terms and stems
  • Chinese traditionalLunisolar
  • Hindu lunisolarVedic, Lahiri ayanamsa
  • Buddhist EraCivil era
  • Saka SamvatTropical solar
  • HijriUmm al-Qura
Read the calendar reference

Almanac generator

The package includes a CLI that renders a full year of synchronized data — useful for testing, research and printed almanacs.

Read the almanac guide

Documentation

QuickstartInstall the package and decode your first timestamp.The seven systemsHow the seven calendars are defined and computed.Almanac generatorGenerate a year of synchronized calendar data.

Hosted API

A hosted service for global holiday data and astronomical events is in development, aimed at HR, payroll and logistics systems that need SLAs. The local library remains free and complete.

No hosted endpoint is live yet. If you need it early, email us — we are onboarding design partners.