README

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

Available SDKs

Language	Package	Version	Documentation
JavaScript/TypeScript	@festivo-io/festivo-sdk		README
Python	festivo-python		README
PHP	festivo-io/festivo-php		README
Go	festivo-sdk-go		README
Ruby	festivo		README
Java	io.github.festivo-io:festivo-sdk		README

Features

• 🌍 250+ Countries - Comprehensive holiday coverage worldwide
• 📅 UTC Dates - Accurate timezone handling for global holidays
• 🏙️ City & Regional - Support for local holidays (Pro/Builder plans)
• ✅ Type Safe - Full type definitions in all supported languages
• ⚡ Modern - Built with current best practices for each language
• 🧪 Well Tested - Comprehensive test suites included

Quick Start

JavaScript/TypeScript

npm install @festivo-io/festivo-sdk

import { FestivoClient } from '@festivo-io/festivo-sdk';
const client = new FestivoClient({ apiKey: 'YOUR_API_KEY' });
const { holidays } = await client.getHolidays('US', 2026);

Python

pip install festivo-python

from festivo import FestivoClient
client = FestivoClient(api_key='YOUR_API_KEY')
result = client.get_holidays('US', 2026)

PHP

composer require festivo-io/festivo-php

use Festivo\FestivoClient;
$client = new FestivoClient('YOUR_API_KEY');
$result = $client->getHolidays('US', 2026);

Go

go get github.com/festivo-io/festivo-sdk-go

import "github.com/festivo-io/festivo-sdk-go/festivo"
client := festivo.NewClient("YOUR_API_KEY")
result, _ := client.GetHolidays("US", 2026, nil)

Ruby

gem install festivo

require 'festivo'
client = Festivo::Client.new('YOUR_API_KEY')
result = client.get_holidays(country: 'US', year: 2026)

Java

Maven:

<dependency>
  <groupId>io.github.festivo-io</groupId>
  <artifactId>festivo-sdk</artifactId>
  <version>0.2.1</version>
</dependency>

Gradle:

implementation 'io.github.festivo-io:festivo-sdk:0.2.1'

import io.festivo.FestivoClient;
FestivoClient client = new FestivoClient("YOUR_API_KEY");
FestivoClient.HolidaysResponse holidays = client.getHolidays("US", 2026, null);

Documentation

• Official Website
• API Documentation
• Get Your API Key

Support

• Email: support@getfestivo.com
• Report Issues

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.