Calendarific SDKs & Libraries: Integrate Holiday Data (2026)

SDKs overview

Calendarific provides programmatic access to holiday data for over 200 countries and 3,000 states and provinces. The API facilitates integration of national, religious, and cultural holidays into various applications, supporting use cases such as event scheduling, payroll systems, and content management that require holiday awareness. To streamline this integration, Calendarific offers a suite of official SDKs and supports community-contributed libraries. These SDKs abstract the underlying HTTP requests and JSON parsing, enabling developers to interact with the Calendarific API using native language constructs rather than direct HTTP client calls.

The core functionality accessible through these SDKs includes retrieving holidays for a specific year and country, filtering holidays by type (e.g., national, local, religious), and validating dates against holiday calendars. The API also supports parameters for specifying language, time zone, and specific holiday categories. Official SDKs are maintained by Calendarific to ensure compatibility with the latest API versions and features, while community libraries often extend functionality or offer alternative implementations for less common programming environments.

Developers can utilize these SDKs to build features such as displaying upcoming holidays on a dashboard, adjusting delivery schedules based on public holidays, or populating calendar applications with relevant holiday information. The API's comprehensive API documentation provides detailed endpoints and parameter explanations, complementing the SDKs by offering a full understanding of the underlying API capabilities.

Official SDKs by language

Calendarific offers official SDKs for several popular programming languages, designed to simplify interactions with its holiday API. These libraries are developed and maintained by Calendarific to ensure they are up-to-date with the latest API specifications and provide a consistent developer experience. Each SDK handles authentication, request formatting, and response parsing, reducing boilerplate code.

The following table outlines the officially supported SDKs, including their respective package names and typical installation commands:

Each of these SDKs provides specific classes or functions for accessing different API endpoints, such as retrieving holidays, checking for specific holiday types, or querying supported countries. For instance, the Python SDK might expose a get_holidays method that accepts parameters like year, country, and API key, returning a structured object containing holiday data. Developers can find detailed usage instructions and method signatures within the Calendarific API documentation specific to each language.

Installation

Installing Calendarific SDKs typically involves using the package manager specific to your chosen programming language. The process is designed to be straightforward, allowing developers to quickly integrate the library into their projects. Below are detailed installation instructions for the primary official SDKs.

JavaScript (Node.js)

For Node.js projects, the calendarific-js package is available via npm. Navigate to your project directory in the terminal and execute the following command:

npm install calendarific-js

This command downloads the package and its dependencies, adding them to your node_modules directory and updating your package.json file. After installation, you can import the library into your JavaScript files using require or import statements.

PHP

PHP projects use Composer for dependency management. To install the calendarific/calendarific-php library, execute this command in your project's root directory:

composer require calendarific/calendarific-php

Composer will download the library and generate an autoloader file. Ensure you include Composer's autoloader in your PHP script (require 'vendor/autoload.php';) to make the Calendarific classes available.

Python

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

pip install calendarific

This command installs the package into your Python environment. Once installed, you can import the package in your Python scripts and begin making API calls. It's often recommended to install packages within a Python virtual environment to manage project dependencies effectively.

Ruby

Ruby projects typically manage dependencies with Bundler, using RubyGems. To install the calendarific-ruby gem, add it to your project's Gemfile:

gem 'calendarific-ruby'

Then, run bundle install in your terminal. Alternatively, for standalone installation without Bundler, use:

gem install calendarific-ruby

Go

Go modules are used to manage dependencies in Go projects. To add the go-calendarific module, navigate to your project directory and execute:

go get github.com/calendarific/go-calendarific

This command fetches the module and updates your go.mod file. You can then import the package into your Go source files.

Quickstart example

This section provides a quickstart example using the Python SDK to retrieve public holidays for a specific country and year. This example demonstrates basic setup, API key configuration, and a simple query.

Python Quickstart

First, ensure you have installed the Python SDK using pip install calendarific. You will also need your Calendarific API key, which can be obtained from your Calendarific account dashboard.

import calendarific

# Replace 'YOUR_API_KEY' with your actual Calendarific API key
api_key = 'YOUR_API_KEY'

# Initialize the Calendarific client
client = calendarific.Client(api_key)

# Define parameters for the holiday request
year = 2026
country = 'US'  # United States

try:
    # Fetch holidays
    response = client.holidays(year=year, country=country)

    # Check if the API call was successful and holidays exist
    if response and 'response' in response and 'holidays' in response['response']:
        holidays = response['response']['holidays']
        print(f"Public holidays in {country} for {year}:")
        for holiday in holidays:
            print(f"- {holiday['name']} on {holiday['date']['iso']}")
    else:
        print("No holidays found or an error occurred.")
        if 'meta' in response and 'error' in response['meta']:
            print(f"API Error: {response['meta']['error']['message']}")

except Exception as e:
    print(f"An unexpected error occurred: {e}")

This Python script initializes the Calendarific client with your API key, then calls the holidays method to fetch public holidays. It iterates through the returned list of holidays, printing each holiday's name and date. Error handling is included to catch potential issues, such as an invalid API key or network problems. Similar examples are available for other languages in the official Calendarific API documentation, demonstrating how to adapt this pattern to JavaScript, PHP, Ruby, and Go.

Community libraries

While Calendarific provides official SDKs for major programming languages, the developer community also contributes libraries and wrappers that can offer additional functionalities, alternative language support, or specific integrations. These community-driven projects are often hosted on platforms like GitHub and can be discovered through searches related to "Calendarific API" and the desired programming language.

Community libraries may vary in their level of maintenance, feature completeness, and adherence to the latest Calendarific API specifications. Before integrating a community library, it is advisable to review its documentation, check its activity on the repository (e.g., recent commits, open issues, pull requests), and assess its suitability for your project's stability requirements. Some community libraries might focus on niche use cases, such as integration with specific frameworks (e.g., a Django package for Calendarific) or providing a more opinionated interface to the API.

For instance, a developer might create a wrapper in an unsupported language like C# or Java, or develop a client that integrates Calendarific data directly into a specific content management system. These contributions demonstrate the flexibility of the Calendarific API and the broader ecosystem of tools available to developers. While official SDKs are recommended for core integrations due to guaranteed support, community libraries can sometimes fill gaps or offer specialized solutions. Developers should always refer to the official Calendarific API documentation as the authoritative source for API endpoint details and data structures, regardless of the client library used.