Developer API

A free, public JSON API for holidays, dates and time-zone-accurate countdowns — no key required. Please keep attribution to CountdownsHQ. Responses are cached and CORS-enabled, so you can call them straight from the browser.

Base URL

https://countdownshq.com/api/v1

Endpoints

GET/holidays

List upcoming holidays, nearest first. Filter with query params: category, country, religion, q (name search), limit (max 200).

https://countdownshq.com/api/v1/holidays?limit=5
https://countdownshq.com/api/v1/holidays?country=vietnam
https://countdownshq.com/api/v1/holidays?category=RELIGIOUS&religion=christianity

GET/holidays/{slug}

Full detail for one holiday: overview, history, meaning, FAQs, traditions, foods, countries and related holidays.

https://countdownshq.com/api/v1/holidays/christmas

GET/holidays/{slug}/countdown

The resolved target instant plus a live remaining breakdown. Pass ?country=<slug> to anchor the target time to that country's time zone.

https://countdownshq.com/api/v1/holidays/christmas/countdown
https://countdownshq.com/api/v1/holidays/tet/countdown?country=vietnam

GET/countries

List all supported countries with their primary time zone.

https://countdownshq.com/api/v1/countries

GET/countries/{slug}

Country detail plus its upcoming holidays, each resolved to the country's time zone.

https://countdownshq.com/api/v1/countries/japan

Response shape

Every successful response is wrapped in a data envelope with meta. Dates use ISO 8601; instant is the exact UTC moment of local midnight for the target time zone.

{
  "data": {
    "slug": "christmas",
    "name": "Christmas",
    "date": {
      "local": "2026-12-25",
      "instant": "2026-12-24T17:00:00.000Z",
      "timezone": "UTC",
      "isConfirmed": true
    },
    "remaining": { "days": 165, "hours": 7, "minutes": 12, "seconds": 4, "totalSeconds": 14284324 }
  },
  "meta": { "apiVersion": "v1", "attribution": "CountdownsHQ — https://countdownshq.com" }
}

No-code option

Just want a countdown on your page? Use the embeddable widget — no code beyond a single <iframe>.