How Our Date Converters Calculate: Methods and Tests
Every converter runs in your browser on published calendar rules or official tables, and each one is tested against dates from the authority behind it.
One day count underneath
Every conversion passes through the Julian Day Number, the continuous count of days astronomers use: 1 January 2000 is day 2,451,545. Converting a date means turning it into that number and the number into the other system, so any converter can be checked against any other. The Gregorian and Julian calendar formulas are the integer algorithms published by Fliegel and Van Flandern and in Jean Meeus's Astronomical Algorithms, and they agree with the US Naval Observatory's Julian Date service.
Rules we compute
- Day of the year, Julian date codes and ISO 8601. Week numbers follow ISO 8601-1:2019: weeks start on Monday and week 1 is the week with the year's first Thursday. Tested for every day from 1600 to 2400.
- Unix time counts seconds since 1970-01-01 00:00 UTC without leap seconds, as POSIX defines it.
- Excel serial dates use Microsoft's 1900 system, including the non-existent 29 February 1900 kept for Lotus 1-2-3 compatibility (serial 60), and the 1904 system.
- Hebrew calendar arithmetic follows the rules set out by Dershowitz and Reingold in Calendrical Calculations, including the postponement rules for Rosh Hashanah. It matches the International Components for Unicode (ICU) Hebrew calendar on every fifth day from 1700 to 2300.
- Persian calendar uses the 33-year leap-year rule, which matches the official astronomical calendar of Iran from 1178 to 1501 SH (1799 to 2123). Nowruz dates were checked against the March equinox times published by the US Naval Observatory.
- Tabular Islamic calendar uses the common 30-year cycle with 11 leap years and matches ICU's civil Islamic calendar from 1900 to 2200.
Calendars that need official tables
Three calendars cannot be computed from a simple formula, so the converters carry compact month-length tables:
- Umm al-Qura (Saudi Arabia), 1300 to 1600 AH. The table comes from ICU and matches all 3,612 month starts published by the King Abdulaziz City for Science and Technology, which maintains the calendar. Commonly copied open-source tables agree only between 1420 and 1450 AH. Countries that start months with a moon sighting can be a day or two different, so the converter has an adjustment.
- Chinese lunar calendar, 1901 to 2100. The table is generated from the open-source lunar-javascript library (MIT licence) and checked against the Hong Kong Observatory's conversion tables, with one correction from those tables for the ninth month of 2057. The calendar built into web browsers gives the wrong date for Chinese New Year in 2027 and 2030, so we do not use it.
- Nepali Bikram Sambat, 1970 to 2090 BS. Month lengths are set by Nepal's calendar committee. Years up to 2083 BS follow the approved calendar, on which three independent sources agree; 2084 BS and later come from the bikram-sambat library (Apache 2.0) and are marked provisional until the committee publishes them.
Test dates
| Check | Expected | Source |
|---|---|---|
| 2000-01-01 12:00 UTC | JD 2451545.0 | US Naval Observatory |
| 1582-10-04 (Julian) and 1582-10-15 (Gregorian) | Consecutive days, JDN 2299160 and 2299161 | US Naval Observatory |
| Excel serial 45658 | 2025-01-01 | Microsoft |
| Unix 2147483647 | 2038-01-19 03:14:07 UTC | POSIX arithmetic |
| 1 Ramadan 1447 / 1448 | 2026-02-18 / 2027-02-08 | KACST (Umm al-Qura) |
| Rosh Hashanah 5787 / 5788 | 2026-09-12 / 2027-10-02 | Hebrew calendar rules |
| Chinese New Year 2026 / 2027 | 2026-02-17 / 2027-02-06 | Hong Kong Observatory |
| 1 Baisakh 2083 BS | 2026-04-14 | Nepal calendar, three sources |
| Nowruz 1405 / 1407 | 2026-03-21 / 2028-03-20 | Equinox times, US Naval Observatory |
The automated tests run these dates and full-range comparisons every time the site is built.
Time zones
Pages show today's date in your device's time zone, so near midnight the date can differ from someone else's. Converters that involve a time of day (Unix time, ISO 8601, Julian Day) say whether a time is UTC or local.
Corrections
If a converter gives a date that disagrees with an official calendar, please tell us through the contact page with the date and the source you are comparing against. We check every report and correct confirmed errors.