Festivo Public Holidays SDKs & Libraries: Official & Community (2026)

SDKs overview

Festivo Public Holidays provides SDKs and client libraries to enable developers to integrate public holiday data and ICS calendar feeds into their applications. These software development kits are designed to simplify interaction with the API by handling common tasks such as HTTP request construction, response parsing, and authentication. Developers can use these tools to query public holidays for specific countries and years, retrieve holiday details, and generate calendar feeds programmatically, abstracting the underlying RESTful API calls. The SDKs aim to reduce boilerplate code and streamline development across various programming environments.

The Festivo Public Holidays API itself is a RESTful service that delivers holiday data in JSON format, as described by architectural principles for web services W3C Web Services Architecture. This design allows for direct HTTP requests, but SDKs offer a higher-level abstraction. Official SDKs are available for a range of popular programming languages, alongside support for cURL for direct command-line interaction or testing. Community-contributed libraries may also extend support or provide specialized integrations, though their maintenance status can vary.

Official SDKs by language

Festivo Public Holidays offers official SDKs and client libraries for several programming languages, designed to facilitate integration with the Public Holiday API and ICS Calendar Feeds. These libraries provide a structured way to access API functionalities, adhering to language-specific conventions. The official documentation includes detailed guides and examples for each supported language, demonstrating how to retrieve holiday data, filter results, and manage API responses.

The following table outlines the officially supported SDKs, including their typical package names and installation methods. Developers are encouraged to consult the Festivo Public Holidays API documentation for the most current versions, detailed usage instructions, and any language-specific prerequisites.

Installation

Installing a Festivo Public Holidays SDK typically involves using a package manager specific to the programming language. These package managers automate the process of downloading dependencies and making the library available for use within a project. The exact command will vary based on the chosen language and environment.

JavaScript (Node.js)

For Node.js environments, the SDK can be installed via npm (Node Package Manager) or Yarn:

npm install festivo-js
# or
yarn add festivo-js

After installation, the library can be imported into JavaScript files using require or ES module syntax.

Python

Python developers can install the SDK using pip, the standard package installer for Python:

pip install festivo-python

Once installed, the library's modules and functions can be imported into Python scripts.

PHP

For PHP projects, Composer is the recommended tool for dependency management:

composer require festivo/festivo-php

This command adds the Festivo PHP client to your project, and Composer's autoloader will make the classes available.

Ruby

Ruby projects typically use Bundler and RubyGems. First, add the gem to your Gemfile:

gem 'festivo-ruby'

Then, install it:

bundle install

Go

Go modules are used to manage dependencies. To add the Festivo Go SDK:

go get github.com/festivo/go-festivo

Then, import the package in your Go source files.

Java

Java projects commonly use Maven or Gradle for dependency management. For Maven, add the following to your pom.xml:

<dependency>
    <groupId>com.festivo</groupId>
    <artifactId>festivo-java</artifactId>
    <version>1.0.0</version> <!-- Replace with actual version -->
</dependency>

For Gradle, add to your build.gradle:

implementation 'com.festivo:festivo-java:1.0.0' // Replace with actual version

C#

.NET projects use NuGet for package management. Install via the .NET CLI:

dotnet add package Festivo.CSharp

Alternatively, use the NuGet Package Manager in Visual Studio.

Quickstart example

The following examples demonstrate how to retrieve public holidays for a specific country and year using various SDKs. A valid API key is required for authentication with the Festivo Public Holidays API. For additional authentication details, refer to the Festivo Public Holidays API documentation.

Python Quickstart

This Python example fetches public holidays for the United States in 2026:

from festivo_python import FestivoClient
import os

# Initialize the client with your API key
api_key = os.getenv("FESTIVO_API_KEY") # Safely retrieve from environment variables
client = FestivoClient(api_key)

try:
    # Get public holidays for a country and year
    holidays = client.get_holidays(country_code='US', year=2026)
    for holiday in holidays:
        print(f"Date: {holiday['date']}, Name: {holiday['name']}, Type: {holiday['type']}")
except Exception as e:
    print(f"An error occurred: {e}")

JavaScript (Node.js) Quickstart

This Node.js example queries public holidays for Germany in 2026:

const FestivoClient = require('festivo-js').FestivoClient;

// Initialize the client with your API key
const apiKey = process.env.FESTIVO_API_KEY; // Safely retrieve from environment variables
const client = new FestivoClient(apiKey);

async function getGermanHolidays() {
  try {
    const holidays = await client.getHolidays('DE', 2026);
    holidays.forEach(holiday => {
      console.log(`Date: ${holiday.date}, Name: ${holiday.name}, Type: ${holiday.type}`);
    });
  } catch (error) {
    console.error(`An error occurred: ${error.message}`);
  }
}

getGermanHolidays();

PHP Quickstart

A PHP example to retrieve holidays for France in 2026:

<?php
require 'vendor/autoload.php';

use Festivo\FestivoClient;

// Initialize the client with your API key
$apiKey = getenv('FESTIVO_API_KEY'); // Safely retrieve from environment variables
$client = new FestivoClient($apiKey);

try {
    $holidays = $client->getHolidays('FR', 2026);
    foreach ($holidays as $holiday) {
        echo "Date: {$holiday['date']}, Name: {$holiday['name']}, Type: {$holiday['type']}\n";
    }
} catch (Exception $e) {
    echo "An error occurred: " . $e->getMessage() . "\n";
}
?>

cURL Quickstart

For direct API interaction without an SDK, cURL can be used. This example fetches holidays for the United Kingdom in 2026:

curl -X GET \
  'https://api.festivo.com/v1/holidays?country=GB&year=2026' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Replace YOUR_API_KEY with your actual Festivo Public Holidays API key. It is recommended to use environment variables for API keys in production environments to ensure secure API key management, as detailed in web security best practices for Mozilla Web Security resources.

Community libraries

While Festivo Public Holidays provides official SDKs, the open-source nature of API integration sometimes leads to community-contributed libraries. These libraries can offer additional language support, specific framework integrations (e.g., for Django, Ruby on Rails, or Spring Boot), or specialized functionalities not present in the official SDKs. Developers often create and maintain these tools to meet particular project requirements or to adapt the API client to niche development patterns.

Community libraries are typically found on platforms like GitHub, npm, PyPI, or as public gems. When considering a community-driven library, it is advisable to evaluate its maintenance status, the activity of its contributors, the extent of its documentation, and its compatibility with the latest version of the Festivo Public Holidays API. While not officially supported, some community libraries can provide valuable alternatives or supplementary tools for integration. Developers should refer to the Festivo Public Holidays developer documentation for any guidelines on community contributions or recommended third-party clients.