# 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 28 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 28 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, `AR` Argentina, `CO` Colombia, `CL` Chile, `PE` Peru, `PT` Portugal, `AT` Austria, `CH` Switzerland, `BE` Belgium.
- Dates are `YYYY-MM-DD`; weekdays are English names; `isoWeekday` is 1 for Monday to 7 for Sunday.
- A holiday's `name` is its English name as written in the country's official list, so it can change when we align a name with that list; match holidays by `date`, not by name. On 15 October 2026 these names changed: United Kingdom — “Early May bank holiday”, “Spring bank holiday” and “Summer bank holiday” (were May Day, Spring Bank Holiday, Late Summer Bank Holiday) and the 2022–2023 one-off days as GOV.UK titles them; Canada — “Labour Day”; Australia — “Anzac Day”; India — “Id-ul-Fitr”, “Id-ul-Zuha (Bakrid)”, “Muharram”, “Milad-un-Nabi or Id-e-Milad (Birthday of Prophet Mohammad)”, “Mahavir Jayanti” and “Christmas Day”, as in the central government's gazetted list; Singapore — “Labour Day”, “Hari Raya Puasa”, “Hari Raya Haji” and “Deepavali”.
- Errors come back as HTTP 400 with `{"error": "...", "message": "..."}`; unknown paths as 404.

The machine-readable description is [openapi.json](https://whathappen.today/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](https://whathappen.today/mcp/server-card) and [/.well-known/mcp/server-card.json](https://whathappen.today/.well-known/mcp/server-card.json); [llms.txt](https://whathappen.today/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 not yet officially confirmed (moon sightings, yearly announcements), 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 28 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](https://whathappen.today/privacy/).
- 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](mailto:hello@whathappen.today) with a link to the official announcement.

Last updated: 15 October 2026

---

Web page: https://whathappen.today/api/