Official Python SDK for the holidays.rest API.
- Python 3.10+
httpx(only dependency)
pip install holidays-restfrom holidays_rest import HolidaysClient
with HolidaysClient(api_key="YOUR_API_KEY") as client:
holidays = client.holidays(country="US", year=2024)
for h in holidays:
print(h.date, h.name.get("en"))Get an API key at holidays.rest/dashboard.
from holidays_rest import HolidaysClient
client = HolidaysClient(
api_key="YOUR_API_KEY", # required
timeout=15.0, # optional, default 15s
)Supports use as a context manager (with statement) to close the underlying connection pool on exit.
from holidays_rest import AsyncHolidaysClient
async with AsyncHolidaysClient(api_key="YOUR_API_KEY") as client:
holidays = await client.holidays(country="US", year=2024)Both clients expose identical methods — only the async/await syntax differs.
| Parameter | Type | Required | Description |
|---|---|---|---|
country |
str |
yes | ISO 3166 alpha-2 code (e.g. "US") |
year |
int | str |
yes | Four-digit year (e.g. 2024) |
month |
int | str |
no | Month filter (1–12) |
day |
int | str |
no | Day filter (1–31) |
type |
str | list[str] |
no | "religious", "national", "local" |
religion |
int | list[int] |
no | Religion code(s) 1–11 |
region |
str | list[str] |
no | Subdivision code(s) — from country() |
lang |
str | list[str] |
no | Language code(s) — from languages() |
response |
str |
no | "json" (default) | "xml" | "yaml" | "csv" |
# All US holidays in 2024
client.holidays(country="US", year=2024)
# National holidays only
client.holidays(country="DE", year=2024, type="national")
# Multiple types
client.holidays(country="TR", year=2024, type=["national", "religious"])
# Filter by month and day
client.holidays(country="GB", year=2024, month=12, day=25)
# Specific region
client.holidays(country="US", year=2024, region="US-CA")
# Multiple regions
client.holidays(country="US", year=2024, region=["US-CA", "US-NY"])countries = client.countries()
for c in countries:
print(c.alpha2, c.name)Returns country details including subdivision codes usable as region filters.
us = client.country("US")
for s in us.subdivisions:
print(s.code, s.name)langs = client.languages()All responses are deserialized into dataclasses.
@dataclass
class Holiday:
country_code: str # e.g. "DE"
country_name: str # e.g. "Germany"
date: str # "YYYY-MM-DD"
name: dict[str, str] # {"en": "New Year's Day", "de": "Neujahr", ...}
is_national: bool
is_religious: bool
is_local: bool
is_estimate: bool # True when the date is algorithmically estimated
day: DayInfo # day-of-week, actual vs observed
religion: str # e.g. "Christianity", empty string if not applicable
regions: list[str] # subdivision codes, e.g. ["BW", "BY"]
@dataclass
class DayInfo:
actual: str # day the holiday falls on, e.g. "Thursday"
observed: str # day it is observed (may differ for weekend holidays)
@dataclass
class Country:
name: str
alpha2: str
subdivisions: list[Subdivision]
@dataclass
class Subdivision:
code: str
name: str
@dataclass
class Language:
code: str
name: strNon-2xx responses raise HolidaysApiError:
from holidays_rest import HolidaysClient, HolidaysApiError
with HolidaysClient(api_key="YOUR_API_KEY") as client:
try:
holidays = client.holidays(country="US", year=2024)
except HolidaysApiError as e:
print(e.status_code) # HTTP status code
print(str(e)) # Error message
print(e.body) # Raw response bytes| Status | Meaning |
|---|---|
| 400 | Bad request |
| 401 | Invalid API key |
| 404 | Not found |
| 500 | Server error |
| 503 | Service unavailable |
MIT