Custom Connector
Calendarific Connector
Global
The Calendarific Connector provides a RESTful interface to comprehensive holiday data — public, bank, local, and religious holidays and observances across 230+ countries and 3,300+ states. It supports querying holiday data by country, year, date, or holiday type.
Overview
Integration Overview
The Calendarific Connector offers the following integration points to query holiday-related data, with optional filters for type and location.
- getHolidaysByCountryYear. Retrieve holidays for a specific country and year.
- getHolidaysByDate. Fetch holidays occurring on a specific date across all countries.
- getSupportedCountries. Retrieve the list of supported countries and their details.
- getHolidaysByType. Fetch holidays filtered by type (national, local, religious).
- getHolidaysWithFilters. Retrieve holidays with customizable filters such as location or category.
Documentation
Detailed Integration Documentation
Holidays by Country & Year
| Operation | getHolidaysByCountryYear |
|---|---|
| Purpose | Retrieves a list of holidays for a specified country and year, with optional filtering. |
| Parameters | Required: api_key; country (ISO 3166-1 two-letter, e.g. US); year (e.g. 2023). Optional: type (e.g. national, local, religious). |
| Output | Successful: a JSON array of holidays (name, description, date, type). Failure: HTTP 422 with error details if required parameters are missing/invalid. |
| Workflow example | GET with api_key, country=US, year=2023, then display holidays in a calendar or event planner. |
Holidays by Date
| Operation | getHolidaysByDate |
|---|---|
| Purpose | Retrieves holidays occurring on a specific date across all supported countries. |
| Parameters | Required: api_key; date (ISO YYYY-MM-DD, e.g. 2023-12-25). |
| Output | Successful: a JSON array of holidays on the specified date. Failure: error if date or api_key is invalid. |
| Workflow example | GET with api_key and date=2023-12-25 to display holidays like Christmas Day across countries. |
Supported Countries
| Operation | getSupportedCountries |
|---|---|
| Purpose | Retrieves a list of all countries supported by the connector. |
| Parameters | Required: api_key. |
| Output | Successful: a JSON array of supported countries (code and name). Failure: error if api_key is invalid. |
| Workflow example | GET with api_key to populate a country dropdown in an application. |
Holidays by Type
| Operation | getHolidaysByType |
|---|---|
| Purpose | Retrieves holidays filtered by a specific type (national, local, religious). |
| Parameters | Required: api_key; country (e.g. US); year (e.g. 2023); type (e.g. religious). |
| Output | Successful: a JSON array of holidays matching the type. Failure: error if parameters are invalid or the type is unsupported. |
| Workflow example | GET with api_key, country=US, year=2023, type=religious to display religious holidays. |
Holidays with Filters
| Operation | getHolidaysWithFilters |
|---|---|
| Purpose | A flexible integration point to query holidays with customizable filters. |
| Parameters | Required: api_key; country; year. Optional: location (e.g. US-NY); type. |
| Output | Successful: a JSON array of holidays matching the filters. Failure: error if required parameters are missing/invalid. |
| Workflow example | GET with api_key, country=US, year=2023, location=US-NY to display New York-specific holidays. |
Example Workflow: Holiday Calendar Application
| Fetch countries | Use getSupportedCountries to populate country options. |
|---|---|
| Retrieve holidays | Use getHolidaysByCountryYear with country=US and year=2023 for a calendar view. |
| Filter by type | Use getHolidaysByType with type=national to highlight national holidays. |
| Monitor | Handle HTTP 422 / 429 for invalid inputs or rate limits, and log calls to optimize performance. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.