GET AI agent ready /v1/holidays/{country}/{year}

Holidays API - GET /holidays/{country}/{year}

REST-convention read endpoint. Pass a 2-letter ISO 3166-1 alpha-2 country code and a 4-digit year in the path. Returns every public holiday for that country-year pair with date, English name, local name, types array, counties (for regional holidays), and launch year when known. Supported year range: 1900-2100.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/holidays/{country}/{year} \
  -H "Content-Type: application/json" \
  -d '{"country":"US","year":2026}'

When to use this API

Cache holiday calendars in a static build

Run this GET at build time for every country you support and commit the JSON alongside your site. Users get offline-capable holiday data with zero runtime API calls.

Cross-check delivery SLA calculators

When quoting a delivery date, subtract every holiday in the destination country-year from the working-day count. The counties field lets you refine for regional variants where it matters.

Power "what is today?" homepage widgets

Fetch the current year once, then compare today's date to the holidays array client-side. Show banners like "Offices closed for Thanksgiving" without a server round-trip per view.

Frequently asked questions

Why is this a GET endpoint?

Reads conform to REST convention (GET for retrieval). The /{country}/{year} path parameters make the response cacheable at CDN and browser layers keyed on country and year.

What does the counties field contain?

For holidays observed only in certain regions (like US state holidays or German Länder), counties holds an array of sub-division codes (e.g., ["US-CA", "US-NY"]). National holidays return null.

What year range is supported?

Integers from 1900 to 2100. Outside this window the endpoint returns INVALID_YEAR with a 400 status. Upstream data coverage is strongest for 2000 onward.

What happens for a country with no holiday data?

The endpoint returns 404 with code NOT_FOUND. A handful of ccTLDs lack public data in the upstream provider; fall back to manual entry for those.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.