Festivo Python SDK

Official Python SDK for the Festivo Public Holidays API. Access holiday data for 250+ countries with accurate UTC dates, regional variations, and city-level holidays.

Features

• 🌍 250+ Countries - Comprehensive holiday coverage worldwide
• 📅 UTC Dates - Accurate timezone handling for global holidays
• 🏙️ City & Regional - Support for local holidays (Pro/Builder plans)
• 🐍 Python 3.9+ - Modern Python with type hints
• 📦 Requests Based - Built on the reliable requests library
• 🧪 Well Tested - Comprehensive test suite with pytest

Installation

pip install festivo-python

Usage

from festivo import FestivoClient
import os

# Initialize client
client = FestivoClient(api_key=os.getenv("FESTIVO_API_KEY"))

# Get all holidays for a country
result = client.get_holidays('US', 2026)
print(f"Found {len(result['holidays'])} holidays")

# Get city-level holidays (Pro plan)
milan = client.get_city_holidays('IT', 'IT-MILAN', 2026)
print(milan['holidays'])

# Get regional holidays (Builder plan)
scotland = client.get_regional_holidays('GB', 'GB-SCT', 2026)

# Check if a specific date is a holiday
check = client.check_holiday('US', '2026-12-25')
if check['is_holiday']:
    print(f"{check['holiday']['name']} on {check['holiday']['observed']}")

API Methods

• get_holidays(country, year, **options) - Get all holidays
• get_city_holidays(country, city_code, year, **options) - Get city-level holidays
• get_regional_holidays(country, region_code, year, **options) - Get regional holidays
• check_holiday(country, date, regions=None) - Check if date is a holiday

Development

For local development with Poetry:

cd festivo-sdk/python
poetry install
poetry run pytest
poetry build

Links

• Official Website
• API Documentation
• GitHub Repository
• PyPI Package

Support

• Email: support@getfestivo.com
• Report Issues

License

MIT License - see LICENSE for details.