Public holidays of a country for a year (2000-2035), with the holidays of a state or region when given: date, weekday, English and local name, categories, and whether it is national or which subdivisions observe it. About 250 countries; filter by month and category (public, bank, government, optional...). subdivision=all lists every regional holiday. Several years at once with years (e.g. 2025,2026 or 2025-2027) or a date range with from/to; the answer then also has years, from and to.
Every response includes credits_used: the credits this call cost.
Parameters
name
type
description
countryrequired
string
Country: ISO code or English name. See /calendar/v1/holiday-countries. Example: US
year
integer
Year (default this year). For several years use years, or from/to for a date range. Example: 2026
subdivision
string
State, province or region code (e.g. TX, BY, ENG) to add its own holidays to the national ones.
category
string
Holiday category: public (default) or the country's others, e.g. bank, government, optional, school, unofficial; comma-separated or all.
month
integer
Only this month (1-12).
years
string
Several years instead of year: comma-separated and/or ranges, e.g. 2025,2026 or 2025-2027 (up to 11 years).
from
string
Start of a date range (YYYY-MM-DD), instead of year; without to, up to the end of that year.
to
string
End of a date range (YYYY-MM-DD), inclusive; without from, from the start of that year.
import os, requests
res = requests.get(
"https://api.api.sh/calendar/v1/holidays",
params={"country": "US"},
headers={"x-api-key": os.environ["APISH_KEY"]},
timeout=120,
)
res.raise_for_status()
data = res.json()
const url = new URL("https://api.api.sh/calendar/v1/holidays");
url.searchParams.set("country", "US");
const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Response
A JSON object with the fields described above, plus raw (the source's own data), cached, fetched_at and credits_used. Errors return {"success": false, "error": "…"} with the HTTP status (see errors). A lookup that ran but found nothing (404) costs the price above; refused calls and errors on our side are free (what's charged).
The fastest way to see the full response is the playground: it runs this endpoint with your account and shows the exact JSON.