Christmas Countdown API

API quick start

GET https://howmanydaysuntil.christmas/wp-json/hdc/v1/countdown

Optional timezone example: ?timezone=Europe/London. Use an IANA timezone name. Invalid names return HTTP 400.

Example response

{
    "methodVersion": "1.0.0",
    "referenceTimezone": "America/New_York",
    "generatedAt": "2026-09-11T13:18:11+00:00",
    "currentDate": "2026-09-11",
    "targetDate": "2026-12-25",
    "targetStartAt": "2026-12-25T05:00:00+00:00",
    "targetWeekday": "Friday",
    "nextMidnightAt": "2026-09-12T04:00:00+00:00",
    "calendarDays": 105,
    "weeks": 15,
    "remainingDaysAfterWeeks": 0,
    "exactSeconds": 9042109,
    "countingRule": "Excludes the current date and includes Christmas Day; December 25 returns zero."
}

Response fields and counting rules

calendarDays is the civil-date difference in the requested timezone. exactSeconds is the exact interval to midnight at the start of Christmas Day. generatedAt is UTC. Responses may be cached for up to 60 seconds, shortened near midnight in the requested timezone so yesterday's calendar answer is not cached into the next date.

The API is read-only, requires no account, and does not receive personal information unless a caller deliberately supplies a timezone parameter. Availability is best-effort; applications should handle network errors and should not use this endpoint for safety-critical deadlines.

Method, versioning, and attribution

See how the countdown is calculated. Consumers should store or display methodVersion when reproducibility matters. If you publish the result, link to the homepage or this documentation so readers can inspect the rule.