Anvil › Docs › /v1/countdown

Countdown API: days until a date, sleeps, weekdays and weekend days

Ask how long until a date and get every count people mean by "days until": calendar days, sleeps (midnights you pass), how many of those days are weekdays or weekend days, whole 24-hour days, inclusive days and the exact days/hours/minutes left. Add a start date to get a progress fraction, and use named events like Christmas or next Monday so you never hard-code the year.

Parameters

Example

Request:

GET https://api.oddlathe.com/v1/countdown?to=2026-12-25&from=2026-11-07T19%3A00&tz=Europe/London&start=2026-11-01

Response (generated by the real code when these docs were last built; random or time-based values will differ for you):

{
 "timezone": "Europe/London",
 "event": null,
 "from": {
  "iso": "2026-11-07T19:00:00+00:00",
  "date": "2026-11-07",
  "time": "19:00:00",
  "weekday": "Saturday",
  "utc_offset": "+00:00",
  "abbreviation": "GMT",
  "dst": false,
  "unix": 1794078000,
  "iso_week": 45,
  "day_of_year": 311
 },
 "to": {
  "iso": "2026-12-25T00:00:00+00:00",
  "date": "2026-12-25",
  "time": "00:00:00",
  "weekday": "Friday",
  "utc_offset": "+00:00",
  "abbreviation": "GMT",
  "dst": false,
  "unix": 1798156800,
  "iso_week": 52,
  "day_of_year": 359
 },
 "target_has_time": false,
 "direction": "future",
 "label": "48 sleeps until Friday 25 December 2026.",
 "calendar_days": 48,
 "sleeps": 48,
 "nights": 48,
 "inclusive_days": 49,
 "full_days": 47,
 "weeks": {
 …

Code examples

curl 'https://api.oddlathe.com/v1/countdown?to=2026-12-25&from=2026-11-07T19%3A00&tz=Europe/London&start=2026-11-01'

const params = new URLSearchParams({
  to: "2026-12-25",
  from: "2026-11-07T19:00",
  tz: "Europe/London",
  start: "2026-11-01"
});
const res = await fetch(`https://api.oddlathe.com/v1/countdown?${params}`);
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data);

import json, urllib.parse, urllib.request

params = urllib.parse.urlencode({"to": "2026-12-25", "from": "2026-11-07T19:00", "tz": "Europe/London", "start": "2026-11-01"})
url = "https://api.oddlathe.com/v1/countdown?" + params
# Send a User-Agent: the edge network refuses Python's default one.
req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.load(r)
print(data)

When it's useful

• "12 sleeps until launch" banners and Slack bot replies
• Advent-style progress bars that fill night by night from a start date
• Showing how many working days (Mon–Fri) are left before a deadline
• Holiday countdowns that roll over to next year automatically with event=christmas

Good to know

• Give to (a date or datetime) or event, not both. from defaults to now; tz (default UTC) decides where midnight falls.
• A date-only target counts to the start of that day (00:00 in tz), so on the day itself direction is today with zero sleeps. Add a time (2026-12-25T07:00) to count to a moment.
• calendar_days is the difference between the two local dates. sleeps (also nights) is the number of midnights passed on the way, which is the same number: from 8 pm on 24 December, Christmas is 1 sleep away even though less than one 24-hour day (full_days = 0) is left.
• weekdays and weekend_days split the days after from up to and including the target day (the mornings you wake up to), so they add up to calendar_days. Bank holidays are not removed; use /v1/workdays for that.
• duration is real elapsed time from timestamps, so it is correct across daylight-saving changes; crosses_dst is true when the two ends have different UTC offsets.
• start adds progress: fraction/percent of the real time elapsed since start, plus nights_total, nights_done and nights_left for a star-per-night strip.
• daylight is a clock-based phase (dawn 05–06, day 07–17, dusk 18–19, night 20–04) for each end, not an astronomical sunrise.
• Past targets return direction=past with the same counts measured backwards and a "… days ago" label. Spans over 200 years are rejected.
• Browser UI: Tooltern countdown (same maths, live ticking, star-per-night strip; nothing leaves your device).

How long until (or since) a date, counted the ways people actually count: calendar days, sleeps (midnights passed in the chosen zone), weekdays (Mon–Fri) and weekend days among the days ahead, whole 24-hour days, inclusive days and days/hours/minutes left. Optional start gives a progress fraction and nights done/left; a clock-based day/night phase is included for each end. Named events cover Christmas, New Year, next Monday/Friday/Saturday, end of month and Halloween. Pure maths; nothing is stored.

Errors

Errors are JSON like {"error": {"code": "…", "message": "…"}}. The ones this endpoint can return:

• bad_param (400): a value is the wrong type or out of range (the message says which)
• bad_timezone (400): the zone isn't a known IANA name
• rate_limited (429): over 60 requests a minute; wait for Retry-After seconds

Questions

Related endpoints

• /v1/date/diffAge, duration and ISO week maths between two dates
• /v1/workdaysCount working days between two dates, or add working days to a date
• /v1/holidays/nextThe next few holidays from today (or a date)
• /v1/timeCurrent time (or any moment) in a time zone, with next DST change

Prefer a page to an API?

• Countdown: days and sleeps until any date on Tooltern: same job, nothing leaves your browser.

Published 7 November 2026 · OpenAPI 3.1 spec · Limits and privacy