Developer API

A free, public JSON API for holidays, dates and time-zone-accurate countdowns — no key required. If you display the data, please credit CountdownsHQ with a visible link (rel="nofollow" is fine). Responses are 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 remaining breakdown computed at request time (never cached; remaining.asOf says when). For a ticking display, count down from date.instant in the browser instead of polling. 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.

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

{
  "data": {
    "slug": "christmas",
    "name": "Christmas",
    "country": "vietnam",
    "date": {
      "local": "2026-12-25",
      "instant": "2026-12-24T17:00:00.000Z",
      "timezone": "Asia/Ho_Chi_Minh",
      "isConfirmed": true
    },
    "remaining": {
      "asOf": "2026-09-28T05:00:00.000Z",
      "totalSeconds": 7560000,
      "days": 87, "hours": 12, "minutes": 0, "seconds": 0
    },
    "ongoing": false,
    "publicHoliday": { "status": "none" },
    "daysOff": []
  },
  "meta": { "apiVersion": "v1", "attribution": "CountdownsHQ — https://countdownshq.com", "docs": "https://countdownshq.com/developers" }
}

With ?country=… the countdown also carries that country's public-holiday status (national, federal, special-non-working, regional, optional, none) and the statutory daysOff for the edition being counted — each with a kind (statutory, substitute,additional, block, optional), optional ISO 3166-2 regions and isConfirmed. For example Independence Day 2027 in the United States returns { "date": "2027-07-05", "kind": "substitute" } because July 4 falls on a Sunday. Country pages resolve their own observance date where it differs from the global one (Epiphany in France, Vesak in Thailand, Eid dates in India and Nigeria).

The holiday detail endpoint adds span (the observed start–end of the edition being counted), countryDates (the date and days off in every linked country for that year), and for recurring events edition / prevEdition (label, hosts, dates, precision, confirmation, facts, result).

Caching & fair use

/holidays, /holidays/{slug} and the /countries endpoints are cached at the edge for up to an hour — they change when a holiday passes or content is updated.
/holidays/{slug}/countdown is never cached: remaining is computed for the moment you call it.
Free, no key, no sign-up. No hard rate limit is enforced today; please cache list and detail responses on your side and avoid polling /countdown more than about once a minute per visitor. Traffic that degrades the service for others may be throttled.
If you display the data, please credit CountdownsHQ with a visible link (rel="nofollow" is fine).

No-code option

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