Christmas Countdown Developer REST API

📡 HTTP Endpoint Specification

The primary endpoint accepts simple HTTP GET requests with optional query parameters to control timezone locality and output formatting:

🚀 Code Snippets in 4 Popular Languages

cURL (Terminal / CLI):

curl -X GET "https://howmanydayuntil.christmas/api/countdown/?timezone=America/Chicago" \
  -H "Accept: application/json"

JavaScript (Browser Fetch / Node.js):

async function getChristmasCountdown(timeZone = 'Europe/London') {
  const url = `/api/countdown/?timezone=${encodeURIComponent(timeZone)}`;
  const response = await fetch(url);
  if (!response.ok) throw new Error('API request failed');
  const payload = await response.json();
  console.log(`Days until Christmas: ${payload.daysRemaining}`);
  console.log(`Total seconds: ${payload.secondsRemaining}`);
  return payload;
}

Python 3 (Requests Library):

import requests

def fetch_countdown(tz="America/New_York"):
    endpoint = "https://howmanydayuntil.christmas/api/countdown/"
    params = {"timezone": tz}
    r = requests.get(endpoint, params=params, timeout=5)
    r.raise_for_status()
    data = r.json()
    print(f"Target: {data['targetDate']} ({data['targetWeekday']})")
    print(f"Remaining Days: {data['daysRemaining']}")
    return data

PHP (Modern cURL / file_get_contents):

<?php
$tz = urlencode('Australia/Sydney');
$json = file_get_contents("https://howmanydayuntil.christmas/api/countdown/?timezone={$tz}");
$data = json_decode($json, true);
echo "Days left: " . $data['daysRemaining'];
?>

📋 Complete JSON Response Schema

⚠️ Error Responses

Invalid parameters return HTTP 400 with a JSON body of the form {"error": "message"}. The three documented cases are:

⚙️ Best Practices, Rate Limits & Caching Guidelines

• Client-Side Polling: Because days decrement at midnight, avoid requesting the endpoint every second. For live ticking second countdowns, fetch the data once on load and calculate subsequent ticks client-side.
• Fair Use: The endpoint is free and keyless. Responses are edge-cached (s-maxage=300), so typical widget and app traffic is lightweight. Please cache results on your side for at least 60 seconds and avoid heavy abusive request volumes — sustained abuse may be throttled by platform-level protection.
• Edge CDN Caching: All responses include Cache-Control: public, max-age=60, s-maxage=300 headers, ensuring instant response times via edge nodes across North America, Europe, and Asia-Pacific.
• CORS Headers: Wildcard CORS (Access-Control-Allow-Origin: *) is enabled on all GET responses, allowing seamless direct fetches from browser single-page applications without proxying.