Public holidays API
Updated 2026-10-12
Use when an agent must know the public holidays of a country and year before scheduling dates.
From an MCP client, add https://tanod.dev/mcp and call get_public_holidays; its free daily calls are applied automatically, no key or signup.
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.
Price and free allowance
USD 0.001 per call, paid in USDC on Base, Polygon, Solana, BNB Chain or Arbitrum with x402. 10 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared with FX rates, QR and geocode. MCP tool: get_public_holidays at https://tanod.dev/mcp, where the free tier is automatic.
Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/util?via=public-holidays-api as a custom connector (steps), then ask in plain words, for example "List the public holidays in Germany for 2026." The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.
Related guides: Currency exchange rates API (ECB reference rates), Weather forecast API without an API key, Reverse geocoding API (offline city data), public holiday and business-day API prices over x402. Back to tanod.dev or the guide index. Results are automated and heuristic.