Public Holidays Getting Started Guide (2026)

Getting started overview

Integrating with the Public Holidays API involves a series of steps designed to enable developers to retrieve holiday data for various countries and regions. This guide focuses on the initial setup: creating an account, obtaining the necessary API keys, and making a first successful API call. The process is foundational for any application requiring accurate, programmatic access to public holiday information for use cases such as scheduling, event management, or business operations.

Upon completion of this guide, users will be equipped to query the Public Holidays API for specific holiday data, laying the groundwork for more advanced integrations. The API supports data for over 200 countries and regions, including country-specific, regional, and observed holidays, which is detailed in the Public Holidays API documentation.

Quick Reference Table

Create an account and get keys

Access to the Public Holidays API requires an account and a valid API key. This key authenticates your requests and links them to your usage allowance.

Account Creation Steps:

1. Navigate to the Pricing Page: Start by visiting the Public Holidays pricing page. This is where you can choose between the free tier, which offers 10,000 requests per month, or one of the paid plans for higher request volumes and additional features.
2. Select a Plan: Choose the 'Free' plan to begin, or select a paid plan that aligns with your anticipated usage. All plans require account registration.
3. Complete Registration: Follow the prompts to create your account. This typically involves providing an email address, setting a password, and agreeing to the terms of service.
4. Verify Email (if required): Some registration processes include an email verification step to confirm your ownership of the provided email address.

Obtaining Your API Key:

Once your account is successfully created and you are logged into your Public Holidays dashboard, your unique API key will be displayed. This key is essential for authenticating all your API requests. It is typically found in a dedicated 'API Key' or 'Developer Settings' section.

• Locate Key: Look for a section explicitly labeled 'API Key' or similar within your personal dashboard.
• Copy Key: Copy the entire API key string. This key is a sensitive credential and should be kept confidential.

The API key functions as a primary authentication method, similar to how many RESTful APIs utilize API keys for request validation, as described in general API authentication documentation.

Your first request

With an API key in hand, you can now make your first request to the Public Holidays API. This example demonstrates how to retrieve public holidays for a specific country and year.

API Endpoint Structure:

The base URL for the Public Holidays API is https://api.public-holidays.io/v1/holidays.

Common parameters include:

• api_key: Your unique API key.
• country: The two-letter ISO 3166-1 alpha-2 country code (e.g., US for United States, DE for Germany).
• year: The year for which you want to retrieve holidays (e.g., 2026).

Example Request (cURL):

This cURL example retrieves all public holidays in Germany for the year 2026. Remember to replace YOUR_API_KEY with your actual API key.

curl -X GET \
  'https://api.public-holidays.io/v1/holidays?api_key=YOUR_API_KEY&country=DE&year=2026'

Example Request (Python):

This Python example uses the requests library to perform the same query.

import requests

api_key = "YOUR_API_KEY"
country_code = "DE"
year = 2026

url = f"https://api.public-holidays.io/v1/holidays?api_key={api_key}&country={country_code}&year={year}"

response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    for holiday in data["holidays"]:
        print(f"Date: {holiday['date']}, Name: {holiday['name']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Expected Response Structure:

A successful request will return a JSON object containing a list of holidays for the specified country and year. Each holiday entry typically includes its date, name, and sometimes type (e.g., public, local).

{
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "Neujahr",
      "type": "public"
    },
    {
      "date": "2026-04-03",
      "name": "Karfreitag",
      "type": "public"
    }
    // ... more holidays
  ]
}

For additional language examples and detailed parameter descriptions, consult the Public Holidays API reference documentation.

Common next steps

After successfully making your first API call, consider these next steps to further integrate the Public Holidays API into your applications:

• Explore Additional Endpoints: Review the API reference for other available endpoints, such as checking specific holiday types, regional holidays, or historical data. The API supports various query parameters to refine your results.
• Implement SDKs: If you are working in JavaScript, PHP, Python, or Ruby, consider using the official SDKs provided by Public Holidays. SDKs can streamline integration by handling authentication, request construction, and response parsing, offering a more idiomatic way to interact with the API rather than raw HTTP requests.
• Error Handling: Implement robust error handling in your code to manage various HTTP status codes and API-specific error messages. This ensures your application can gracefully handle issues such as invalid API keys, rate limits, or malformed requests.
• Rate Limiting Management: Understand the rate limits applicable to your chosen plan. Implement a strategy, such as exponential backoff, to manage requests and prevent exceeding your allocated quota, which is a common practice in API rate limit best practices.
• Caching Strategies: For frequently requested static data, implement client-side or server-side caching to reduce the number of API calls and improve application performance. Holiday data for past or distant future years is generally static and can be effectively cached.
• Security Best Practices: Always keep your API key secure. Avoid hardcoding it directly into client-side code, and consider using environment variables or a secure configuration management system.
• Monitor Usage: Regularly check your API usage statistics within your Public Holidays dashboard to monitor consumption and ensure you remain within your plan's limits.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following troubleshooting steps:

• API Key Validation: Double-check that your API key is correct and included in the request. An incorrect or missing API key is a common cause of authentication errors (e.g., HTTP 401 Unauthorized). Ensure there are no leading or trailing spaces.
• Parameter Accuracy: Verify that all required parameters (api_key, country, year) are correctly spelled and have valid values. For instance, ensure the country code is the correct ISO 3166-1 alpha-2 code.
• HTTP Status Codes: Examine the HTTP status code returned in the API response. Common codes to look for include:
  • 200 OK: Request was successful.
  • 400 Bad Request: Often indicates missing or invalid parameters. Check your URL query string.
  • 401 Unauthorized: Your API key is likely missing or incorrect.
  • 403 Forbidden: You may not have permission to access the requested resource, or your API key's plan may not cover the feature.
  • 429 Too Many Requests: You have exceeded your rate limit. Wait and retry, or consider upgrading your plan.
  • 5xx Server Error: An issue on the API provider's side. If this persists, check the Public Holidays status page or contact support.
• Response Body Inspection: Always inspect the response body for detailed error messages, even if the status code is not 200. The API often provides specific explanations for errors in JSON format.
• Cross-check Documentation: Compare your request against the examples and parameter definitions in the Public Holidays documentation. Ensure your endpoint URL and query structure match the API specification.
• Network Issues: Confirm your internet connection is stable and that no firewalls or proxies are blocking your outgoing requests to the API endpoint.
• SDK Specific Issues: If using an SDK, ensure it is correctly installed and configured. Check the SDK's specific error handling mechanisms and documentation.