Date and holiday API for programs and AI agents

Free JSON endpoints and an MCP server that tell a program — or a language model — today's date in any time zone, the week number and whether it is a public holiday. No key, no sign-up, any origin.

Why this exists

Language models do not know what day it is unless someone tells them, and when an app does pass a date it is often the server's UTC date, a day off for users east or west of Greenwich. Ask this API for the user's time zone and you get the local date, the weekday and ISO week, and — for 20 countries — whether today is a holiday, with substitute days and lunar-calendar uncertainty spelled out instead of guessed.

Quick start

curl "https://whathappen.today/api/today?tz=America/New_York&country=US"

Example response (for 9 October 2026, 06:51 UTC):

{
  "date": "2026-10-09",
  "year": 2026,
  "month": 10,
  "monthName": "October",
  "day": 9,
  "weekday": "Friday",
  "isoWeekday": 5,
  "isoWeek": 41,
  "isoWeekYear": 2026,
  "isoWeekLabel": "2026-W41",
  "dayOfYear": 282,
  "daysInYear": 365,
  "daysLeftInYear": 83,
  "isLeapYear": false,
  "quarter": 4,
  "isWeekend": false,
  "timezone": "America/New_York",
  "utcOffset": "-04:00",
  "moon": {
    "phase": "Waning Crescent",
    "emoji": "🌘",
    "illumination": 0.011,
    "ageDays": 28.5
  },
  "country": {
    "code": "US",
    "name": "United States",
    "isPublicHoliday": false,
    "holidays": [],
    "isMakeupWorkday": false,
    "isWorkingDay": true,
    "nextHoliday": {
      "date": "2026-10-12",
      "name": "Columbus Day",
      "weekday": "Monday",
      "observed": false,
      "estimated": false,
      "daysUntil": 3
    },
    "provisional": false,
    "scope": "The 11 federal holidays set by 5 U.S.C. 6103.",
    "official": "https://www.opm.gov/policy-data-oversight/pay-leave/federal-holidays/"
  },
  "localTime": "2026-10-09T02:51:38-04:00",
  "utc": "2026-10-09T06:51:38Z",
  "statement": "Today is Friday, 9 October 2026 in America/New_York (UTC-04:00) — ISO week 41, the 282nd day of 2026 with 83 days left. It is not a public holiday in United States. The next public holiday is Columbus Day on Monday, 12 October 2026 (in 3 days).",
  "timezoneSource": "parameter",
  "disclaimer": "Holiday dates are for reference only. Governments can add, move or cancel holidays; confirm with the official source before relying on them.",
  "holidaySource": {
    "data": "python holidays 0.106 (MIT, https://github.com/vacanza/holidays)",
    "note": "Generated at build time and checked against official calendars for 2026; each country lists an official page to confirm dates."
  }
}

Endpoints

GET	Parameters	Returns
`/api/today`	tz, country	Today's date in a time zone: weekday, ISO week, day of year, days left, moon phase, UTC offset, and with `country` whether today is a public holiday there plus the next one. Includes `statement`, one sentence to quote.
`/api/date`	date (required), tz, country	The same facts for any date from 0001-01-01 to 9999-12-31, plus `daysFromToday`.
`/api/holidays`	country (required), year	Every public holiday of a year (2020–2030), with `observed` for substitute days off and `estimated` for moon-sighting dates; for China also `makeupWorkdays`.
`/api/next-holiday`	country (required), tz, count (1–20)	The next holidays after today, each with `daysUntil`.
`/api/countries`	—	The 20 supported countries, their default time zone and what each list covers.
`/api/on-this-day`	date (MM-DD or YYYY-MM-DD), type, limit, tz	Events, births, deaths and observances for a date, with the Wikipedia attribution (CC BY-SA 4.0) you must show if you display them.

tz is an IANA time-zone name such as Europe/London or Asia/Kolkata. Without it, the country's main zone is used, or UTC when there is no country; the answer's timezoneSource says which.
country is an ISO 3166-1 alpha-2 code: US United States, GB United Kingdom, CA Canada, AU Australia, IN India, IE Ireland, NZ New Zealand, ZA South Africa, SG Singapore, PH Philippines, CN China, DE Germany, JP Japan, FR France, IT Italy, BR Brazil, KR South Korea, MX Mexico, ES Spain, AE United Arab Emirates.
Dates are YYYY-MM-DD; weekdays are English names; isoWeekday is 1 for Monday to 7 for Sunday.
Errors come back as HTTP 400 with {"error": "...", "message": "..."}; unknown paths as 404.

The machine-readable description is openapi.json (OpenAPI 3.1).

A year of holidays

curl "https://whathappen.today/api/holidays?country=GB&year=2026"

{
  "country": {
    "code": "GB",
    "name": "United Kingdom",
    "scope": "Bank holidays in England and Wales.",
    "official": "https://www.gov.uk/bank-holidays"
  },
  "year": 2026,
  "count": 9,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "weekday": "Thursday",
      "observed": false,
      "estimated": false
    },
    {
      "date": "2026-04-03",
      "name": "Good Friday",
      "weekday": "Friday",
      "observed": false,
      "estimated": false
    },
    "…"
  ],
  "provisional": false,
  "disclaimer": "Holiday dates are for reference only. Governments can add, move or cancel holidays; confirm with the official source before relying on them.",
  "holidaySource": {
    "data": "python holidays 0.106 (MIT, https://github.com/vacanza/holidays)",
    "note": "Generated at build time and checked against official calendars for 2026; each country lists an official page to confirm dates."
  }
}

MCP server

The same answers are available as tools over the Model Context Protocol (Streamable HTTP, stateless, no authentication) at:

https://whathappen.today/mcp

Claude Code: claude mcp add --transport http whathappen https://whathappen.today/mcp. Other clients: add a remote server with that URL. The server card is at /mcp/server-card and /.well-known/mcp/server-card.json; llms.txt summarises the site for models.

Tool	What it does	Inputs
`today`	Today's date in a time zone: weekday, ISO week, day of the year, days left in the year, moon phase and UTC offset. With a country, also whether today is a public holiday there and the next holiday. Call this whenever the current date matters — models do not know it reliably.	timezone (IANA name, e.g. Asia/Tokyo), country (ISO code, e.g. JP)
`date_info`	Weekday, ISO week, day of the year, moon phase and (with a country) holiday status for any date from 0001-01-01 to 9999-12-31, plus how many days it is from today.	date (YYYY-MM-DD), timezone, country
`holidays`	All public holidays of one country for a year (2020–2030), including substitute days off, dates that depend on a moon sighting, and China's make-up working days.	country, year
`next_holiday`	The next public holidays of a country after today (in the country's or the given time zone), with the number of days until each.	country, timezone, count (1–20)
`on_this_day`	Notable events, births, deaths and observances for a calendar day, from Wikipedia (CC BY-SA 4.0; the result carries the attribution to show).	date (MM-DD or YYYY-MM-DD; default today), kind (events, births, deaths, observances or all), limit (1–30), timezone
`list_countries`	The 20 countries with holiday data, their default time zone and what each list covers.	none

Limits and good manners

60 requests a minute per IP address. Past that limit the API answers 429 Too Many Requests, and the Retry-After header says how many seconds to wait. For bulk work, fetch a year of holidays once and keep it.
Responses allow any origin (Access-Control-Allow-Origin: *), so browser apps can call the API directly.
We do not log IP addresses, parameters or tool inputs. See the privacy page.
Holiday data covers 2020–2030 and is for reference: governments add and move holidays, and dates marked estimated depend on a moon sighting. Each response includes the country's official source.
On-this-day text is from Wikipedia under CC BY-SA 4.0. If you show it, show the attribution in the response too.

Found a wrong date? Write to hello@whathappen.today with a link to the official announcement.