Build a country holiday calendar in Python

A country picker and a holiday calendar need different information. The countries reference endpoint describes supported calendars; the holidays endpoint returns dated events for the selected year. This guide keeps those steps separate so your application does not accidentally display metadata as its holiday list.

Choose the correct operation

Use GET /v1/holidays/{year}/{country} for the dated list. Supply an ISO alpha-2 or alpha-3 country code, such as US, DE or DEU, and a year from 1900 to 2100. Calendar-specific historical coverage still varies.

import os
import httpx

base_url = "https://holidays-business-days-api1.p.rapidapi.com"
headers = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": "holidays-business-days-api1.p.rapidapi.com",
}
response = httpx.get(
    base_url + "/v1/holidays/2026/US",
    headers=headers, timeout=120
)
response.raise_for_status()
print(response.json())

Choose a published marketplace listing containing this exact operation. A countries-only reference listing is not enough. The website demo has its own small allowance; the scripts below use your marketplace subscription.

Fetch a regional calendar

Install httpx with python -m pip install httpx and set RAPIDAPI_KEY to the key for your active subscription. This script requests Bavaria, rather than Germany's national calendar alone.

import os
from pathlib import Path
import json
import httpx

host = "holidays-business-days-api1.p.rapidapi.com"
year, country = 2026, "DE"
response = httpx.get(
    f"https://{host}/v1/holidays/{year}/{country}",
    headers={
        "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
        "X-RapidAPI-Host": host,
    },
    params={"subdivision": "BY", "observed": "true"},
    timeout=30,
)
response.raise_for_status()
body = response.json()
assert body["country"] == country and body["year"] == year
assert isinstance(body["holidays"], list)
assert body["count"] == len(body["holidays"])
for holiday in body["holidays"]:
    print(holiday["date"], holiday["name"], holiday["local_name"])
Path("holidays.json").write_text(
    json.dumps(body, ensure_ascii=False, indent=2), encoding="utf-8"
)

For this calendar, Epiphany on January 6 is a useful regional check. Removing subdivision=BY selects the national calendar, which has different coverage. Do not use that one comparison as a universal test for every country.

Build the picker from reference data

Use GET /v1/countries for the supported country list, then GET /v1/countries/{country} for available regions, languages and categories. Do not invent subdivision codes or assume all countries expose the same categories.

The holidays response includes the requested year, normalized country code, count, language, calendar version and sorted holiday records. Each record contains a date, weekday, display name, local name, categories and observed flag. Keep dates as calendar dates; converting midnight to a user's time zone can move the displayed day.

Handle observed days and failures

observed=true includes days off moved by observance rules. Use observed=false only when your application deliberately excludes those dates. For a delivery deadline, use the business-day endpoints rather than simply counting weekdays around your visible holiday list.

Correct HTTP 422 inputs before retrying. On 429, check the subscription allowance first; an exhausted quota does not benefit from a retry loop. Retry temporary service failures only within a small budget and honor Retry-After. Calls and retries may consume allowance.

Holiday rules can change through exceptional announcements. Preserve calendar_version, review the returned coverage and verify consequential dates against official announcements.