Festivo Public Holidays Getting Started: API Integration (2026)

Getting started overview

Integrating the Festivo Public Holidays API involves creating an account, obtaining an API key, and then making authenticated requests to retrieve holiday data. The API provides endpoints for querying public holidays by country, year, and specific dates. It also offers functionality to generate ICS calendar feeds, allowing for broader calendar synchronization.

The core process for a new integration typically follows these steps:

1. Account Creation: Register for a Festivo account to access the API.
2. API Key Retrieval: Locate your unique API key within the developer dashboard.
3. First Request: Construct and execute an API call using your key to fetch holiday data.
4. Integration: Incorporate the API into your application logic, handling responses and potential errors.

Festivo offers comprehensive documentation and code examples in multiple programming languages, including JavaScript, Python, PHP, Ruby, Go, Java, Node.js, C#, and Curl, to facilitate the integration process. These resources cover various API endpoints and common use cases.

Here is a quick-reference guide for getting started:

Create an account and get keys

To begin using the Festivo Public Holidays API, you must first create an account on the Festivo platform. This process typically involves providing an email address and setting a password. Upon successful registration, you will gain access to your personal developer dashboard.

Within the developer dashboard, your unique API key will be displayed. This key is essential for authenticating all your API requests. It acts as a credential that authorizes your application to access Festivo's services. Keep your API key confidential, as unauthorized access could lead to misuse of your API quota.

Festivo offers a Developer Plan free tier, which includes 5,000 requests per month. This tier is suitable for initial testing and small-scale integrations. For higher request volumes or additional features, paid plans are available, starting with the Basic Plan at $9 per month for 50,000 requests.

When making API calls, your API key will generally be passed as a query parameter in the request URL. For example, a common parameter name might be api_key or key, followed by your unique string. Refer to the Festivo API documentation for specific parameter names and authentication methods.

Your first request

After obtaining your API key, the next step is to make your first API request to verify the setup and retrieve some data. A common first request is to fetch public holidays for a specific country and year. For instance, you might query for holidays in the United States for the current year.

The Festivo Public Holidays API typically uses a RESTful architecture, where resources are accessed via standard HTTP methods (GET, POST, etc.) and data is returned in JSON format. An example endpoint for retrieving holidays might look like /v1/holidays, with parameters for country, year, and your API key.

Here’s an example using curl, a command-line tool for making HTTP requests:

curl "https://api.festivo.com/v1/holidays?api_key=YOUR_API_KEY&country=US&year=2026"

Replace YOUR_API_KEY with your actual API key and adjust the country and year parameters as needed. The response will be a JSON object containing an array of holiday objects, each detailing a holiday's name, date, and other relevant information.

For programmatic access, Festivo provides SDKs in various languages. Below are examples for making a similar request using Python and JavaScript:

Python Example

Using the requests library:

import requests

api_key = "YOUR_API_KEY"
country_code = "US"
year = 2026

url = f"https://api.festivo.com/v1/holidays?api_key={api_key}&country={country_code}&year={year}"

try:
    response = requests.get(url)
    response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)
    holidays = response.json()
    for holiday in holidays['holidays']:
        print(f"Holiday: {holiday['name']}, Date: {holiday['date']}")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

JavaScript (Node.js) Example

Using the fetch API (available in modern Node.js versions and browsers):

const fetch = require('node-fetch'); // For Node.js environments

const apiKey = "YOUR_API_KEY";
const countryCode = "US";
const year = 2026;

async function getHolidays() {
  const url = `https://api.festivo.com/v1/holidays?api_key=${apiKey}&country=${countryCode}&year=${year}`;

  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    data.holidays.forEach(holiday => {
      console.log(`Holiday: ${holiday.name}, Date: ${holiday.date}`);
    });
  } catch (error) {
    console.error("Error fetching holidays:", error);
  }
}

getHolidays();

These examples demonstrate how to construct the URL, send the request, and parse the JSON response. Ensure you handle potential network errors and API-specific error codes in your application.

Common next steps

Once you have successfully made your first API call and confirmed connectivity, consider these common next steps to further integrate Festivo Public Holidays into your application:

1. Explore Additional Endpoints: Review the Festivo API reference to discover other available endpoints. These might include querying for specific holiday types, retrieving a list of supported countries, or generating ICS calendar feeds. Understanding the full range of API capabilities will help you leverage the service more effectively.
2. Implement Error Handling: Robust applications anticipate and manage errors. Implement error handling mechanisms to gracefully manage scenarios such as invalid API keys, rate limits, or malformed requests. The API documentation will detail specific error codes and their meanings.
3. Manage API Keys Securely: Ensure your API key is stored and transmitted securely. Avoid hardcoding keys directly into your source code, especially for client-side applications. Consider using environment variables, configuration files, or a secure secrets management service for server-side applications.
4. Monitor Usage: Regularly check your API usage against your plan limits. Your Festivo dashboard provides metrics on your request volume. This helps prevent unexpected service interruptions due to exceeding your quota.
5. Utilize SDKs: If you are working in one of the supported languages (JavaScript, Python, PHP, Ruby, Go, Java, Node.js, C#), consider using the official SDKs. SDKs abstract away much of the HTTP request boilerplate, making integration simpler and less error-prone.
6. Cache Data: For static data like public holidays, consider implementing caching strategies. Retrieving the same holiday data repeatedly can consume your API quota unnecessarily. Cache holiday data locally for a reasonable period to reduce API calls and improve application performance.
7. Explore ICS Calendar Feeds: If your application requires users to subscribe to holiday calendars, investigate the ICS Calendar Feeds feature. This allows for dynamic generation of calendar files that can be imported into popular calendar applications.

By following these steps, you can build a more resilient and efficient integration with the Festivo Public Holidays API.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps and potential solutions for common problems:

• 401 Unauthorized / Invalid API Key:

  • Check Key Accuracy: Double-check that your API key is copied exactly as it appears in your Festivo dashboard, without any extra spaces or characters.
  • Key Placement: Ensure the API key is passed correctly as a query parameter (e.g., ?api_key=YOUR_KEY) in your request URL, as specified in the Festivo API documentation.
  • Account Status: Verify your Festivo account is active and not suspended.

• 400 Bad Request / Invalid Parameters:

  • Parameter Names: Confirm that parameter names (e.g., country, year) exactly match those required by the API.
  • Parameter Values: Ensure that parameter values are in the correct format (e.g., country code like US, year as an integer like 2026). Refer to the Festivo documentation for valid parameter values and formats.
  • Required Parameters: Make sure all mandatory parameters for the endpoint are included in your request.

• 403 Forbidden / Rate Limit Exceeded:

  • Check Usage: Review your API usage in your Festivo dashboard. If you've exceeded your free tier limit, you might need to upgrade your plan.
  • Request Frequency: If you're making many requests in a short period, consider adding delays between calls or implementing client-side rate limiting.

• 5xx Server Error:

  • Retry: Occasionally, server-side issues are temporary. Waiting a moment and retrying the request can resolve the problem.
  • Check Status Page: Look for a Festivo status page (if available) or their official communication channels for service outages.

• Network Issues:

  • Internet Connectivity: Verify your local internet connection.
  • Firewall/Proxy: If you are behind a corporate firewall or proxy, ensure it is configured to allow outbound connections to api.festivo.com. For more information on network configurations, refer to Cloudflare's network fundamentals which explains how DNS and proxies interact.

• JSON Parsing Errors:

  • Valid JSON: Ensure the API response is valid JSON. Tools like online JSON validators can help.
  • Content-Type Header: Verify the response's Content-Type header is application/json.

When troubleshooting, always consult the official Festivo documentation for the most accurate and up-to-date information regarding error codes, parameter specifications, and best practices.