Why countdown timers are often a day off (inclusive vs exclusive, midnight, UTC)
You set a countdown to Friday and by Thursday evening it already says "0 days". Or two apps disagree by one. Almost always the apps are using different definitions of "a day", not broken clocks.
The Christmas Eve test
| Measure | 24 Dec 20:00 → 25 Dec | What people expect |
|---|---|---|
| Sleeps / calendar days | 1 | "One sleep until Christmas" |
| Whole 24-hour days | 0 | Often what raw timestamp maths prints |
| Inclusive days | 2 (24th and 25th) | Some event / hotel night counters |
| Hours left | ~4 | Live ticking clocks |
If an app only shows floor((target − now) / 86400), Christmas Eve evening becomes "0 days" and feels a day early. The countdown labels both numbers so the gap is obvious.
Inclusive vs exclusive
- Exclusive / sleeps — midnights still ahead; the target morning is not an extra "day left".
- Inclusive — both the start date and the end date count ("Friday to Sunday is 3 days").
- Half-open API ranges —
fromincluded,toexcluded (common in workday APIs). Read the docs for /v1/workdays and /v1/countdown.
Midnight and time zones
"Friday" means the civil date in some zone. A deadline stored as 2026-12-25T00:00:00Z is still Thursday evening in New York. Always ask: whose midnight? The countdown's zone picker (and Anvil's tz= parameter) make that explicit. Meeting across zones? Cross-check with the time zone planner.
UTC vs local wall time
- Server jobs that use UTC dates will disagree with a phone using local dates near the zone boundary.
- Daylight-saving transitions change how many real hours sit inside a "day"; timestamp subtraction stays correct, naive "add 24 hours" loops do not.
- Unix seconds help debug the exact instant — see the Unix time converter — but humans still need the calendar interpretation.
How to pick the right number
- Promising a child Christmas? Use sleeps.
- Promising a client a delivery day? Use working days (guide) and name the zone.
- Building a timer UI? Show hours when under 48 hours, and label whether you mean calendar days or 24-hour blocks.
Related
Countdown · How many sleeps until Christmas · Working days until a deadline · Date difference · Unix time · Time zone planner · Anvil countdown API
Questions
Why does my countdown say 0 days on Christmas Eve?
It is probably counting whole 24-hour periods. On the evening of the 24th fewer than 24 hours remain, so that count is 0, while sleeps / calendar days is still 1.
What is inclusive day counting?
Counting both the start date and the end date. Friday to Sunday inclusive is 3 days; exclusive sleeps from Friday to Sunday is 2.
Can UTC make a countdown wrong by a day?
Yes. A midnight UTC target is still the previous local evening in the Americas, so the civil date disagrees unless you pick a zone.
Sleeps vs full days — which should I show?
Sleeps for human "nights until" questions; full 24-hour days or a live HH:MM:SS clock when the remaining time is under a day.
Where can I see all the measures at once?
https://tooltern.oddlathe.com/countdown shows sleeps, calendar days, inclusive days, full days, weekdays and weekend days together.
Published .