Public holiday API for 250 countries (free JSON & iCal)

Public holidays for 247 countries and regions as JSON and iCalendar. Names in 12 languages, with each country's weekend (e.g. Friday–Saturday in parts of the Middle East) and make-up working days (e.g. China). No API key, CORS enabled.

{
  "country": "DE",
  "name": {
    "en": "Germany",
    "ja": "ドイツ",
    …
  },
  "years": [2025, 2026, 2027, 2028],
  "weekend": [0, 6],
  "holidays": [
    {
      "date": "2025-01-01",
      "name": {
        "en": "New Year's Day",
        "ja": "元日",
        …
      },
      "local": "Neujahr",
      "observed": false,
      "status": "rule"
    },
    {
      "date": "2025-04-18",
      "name": {
        "en": "Good Friday",
        "ja": "聖金曜日",
        …
      },
      "local": "Karfreitag",
      "observed": false,
      "status": "rule"
    },
    …
  ],
  "workdays": []
}

const res = await fetch("https://holiday.omikuji.dev/api/v1/country/de.json");
const de = await res.json();

// Is 2026-10-03 a public holiday in Germany?
const h = de.holidays.find(
  (x) => x.date === "2026-10-03" && !x.regions && !x.scope
);
h?.name.en; // → "German Unity Day"

Countries and regions

• GET /api/v1/country/{cc}.json Lowercase ISO 3166-1 alpha-2 code (e.g. us, cn, jp). 247 countries and regions, from last year to two years ahead (Japan from 1955)
• GET /ical/{lang}/{cc}.ics iCalendar (nationwide holidays only). lang is one of en, zh-cn, zh-tw, ko, es, fr, de, pt, ru, ar, hi (Japanese names: /ical/{cc}.ics). Subscribe from Google Calendar, iPhone or Outlook

Fields

weekend

Weekend days (0 = Sunday … 6 = Saturday). e.g. United States [0, 6], Saudi Arabia [5, 6]

weekendChanges

Only for countries whose weekend changed (e.g. Nepal from 2026-04-06)

holidays[].name

Holiday name in 12 languages. local is the name in the local language

holidays[].status

official = checked against government data / rule = computed from the legal rules / estimated = not yet announced or depends on moon sighting

holidays[].observed

true for a substitute day moved from a weekend

holidays[].regions

Only some regions (states, provinces). Absent = nationwide

holidays[].scope

"government" = days off for government offices only (e.g. Indonesia's collective leave)

workdays

Weekend days that are working days (e.g. China's make-up working days). offDay is the day off it replaces

years / announcedThrough

Years included / last year announced by the government

Japan (Cabinet Office data, 1955 onward)

Japan is also available from the country endpoint (jp). These older Japan-only endpoints return Japanese names.

• GET /api/v1/holidays.json All years (1955–2027) as date: name
• GET /api/v1/{year}.json One year (same as /api/v1/years/{year}.json)
• GET /api/v1/next.json Next holiday (date / name / renkyu, updated daily)
• GET /api/v1/detail.json As an array; kind tells national holiday, substitute holiday and citizens' holiday apart
• GET /ical/jp.ics iCalendar (from ten years ago to the last announced year)

Usage notes

• Free, no sign-up. The files are static and updated monthly, so please cache them rather than fetching the same file repeatedly.
• Estimated holidays may move when the government announces them. For anything important, check the official announcement too.
• Paths not listed here (e.g. /api/v1/holiday.json) return 410, so res.json() will fail.
• For AI assistants there is also an MCP server: Public holidays for AI assistants