API

Please read the terms of service before using the API.

Endpoints

Click on the cards to view more information about each endpoint.

Note

Except for /joke, all endpoints have an IP-based rate limit of 2 requests per 10 seconds. If you exceed this limit, you will be blocked for 10 seconds. To make your own live countdown, use christmas.js. Jokes are not rate-limited.

/api/is-today

Check if today is Christmas Day

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON boolean, true or false.

Example

true

/api/is-tomorrow

Check if today is Christmas Eve

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON boolean, true or false.

Example

true

/api/joke

Get a Christmas joke

Query parameters

Name	Required?	Default
`language`	No	`en`

Response

Returns a JSON object with a question and answer property

Example

{
	"question": "What do you call a snowman with a six pack?",
	"answer": "An abdominal snowman!"
}

/api/percentage

Get the current countdown complete percentage

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON number.

Example

86.55251292873983

/api/timeleft/

Get the time left until Christmas in all units

This returns the same numbers as /timeleft/:period, but all periods in a single request.

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON object.

Example

{
	"months": 1.6100726825288403,
	"weeks": 7.015316686507936,
	"sleeps": 50,
	"days": 49.10721679398148,
	"hours": 1178.5732030555555,
	"minutes": 70714.39218333333,
	"seconds": 4242863.531
}

/api/timeleft/:period

Get the time left until Christmas in a given unit

Path parameters

`period`

Can be one of:

months
weeks
sleeps
days
hours
minutes
seconds

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON number.

Example

49.11484347222222

/api/timeleft/total

Get the total time left until Christmas

Warning

This route gives the current live countdown. Please DO NOT make requests every second. Either only make requests upon user interaction, or only refresh every hour. If you want a live countdown, embed the fullscreen countdown page with an iframe, or use christmas.js to make your own.

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON object.

Example

{
	"days": 49,
	"hours": 2,
	"minutes": 44,
	"seconds": 33
}

/api/weekday

Get the day of the week that Christmas Day is on

Query parameters

Name	Required?	Default
`timezone`	No	`UTC`

Response

Returns a JSON string.

Example

"Monday"

Query parameters

`language`

You may optionally specify the joke language with ?language=. The language defaults to en, and can be one of:

en

`timezone`

You may optionally specify the timezone with ?timezone=. The timezone defaults to UTC and can be any valid IANA timezone name. If not an exact match, the API will attempt to find a valid timezone given the input. For example, London and GMT will resolve to Europe/London. If a valid timezone can’t be resolved the API will respond with a HTTP 400 status code.