Public holidays API

POST a country code and a year to /v1/holidays and get that country's public holidays with dates, weekdays and names. Optional subdivision and language narrow the result.

Request

country is an ISO 3166-1 alpha-2 code; year is 1990 to 2100. A subdivision can be a code or name (for example CA or California for the US).

curl -s -X POST https://tanod.dev/v1/holidays \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"country":"PH","year":2026}'

Response

{
  "country": "PH",
  "subdivision": null,
  "year": 2026,
  "language": "en_US",
  "count": 20,
  "holidays": [
    {"date": "2026-01-01", "weekday": "Thursday", "name": "New Year's Day"},
    {"date": "2026-02-17", "weekday": "Tuesday", "name": "Chinese New Year"},
    {"date": "2026-03-20", "weekday": "Friday", "name": "Eid al-Fitr"},
    {"date": "2026-04-02", "weekday": "Thursday", "name": "Maundy Thursday"},
    ...
  ]
}

Limits and caveats

Computed from rules, not an official calendar. The holidays are computed from the python-holidays library (MIT licence), including observed and substitute days. No official calendar is consulted.

Estimates exist. Lunar, religious and one-off holidays can be estimates or missing for some years. Confirm with an official source for legal or payroll use.

Unsupported input is a 422 and is not charged.

Related guides: Currency exchange rates API (ECB reference rates), Weather forecast API without an API key, Reverse geocoding API (offline city data). Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.