Calendarific Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating Calendarific involves a sequence of steps designed to get you from account creation to a successful API call. The core process includes signing up for a Calendarific account, which provides access to an API key. This key authenticates your requests to the Calendarific API endpoints. Once you have your key, you can construct an HTTP GET request to retrieve holiday data, specifying parameters such as country, year, and optionally, a specific month.

Calendarific offers a Developer Plan that includes up to 1,000 requests per month at no cost, allowing for initial development and testing without immediate financial commitment. Paid plans, like the Hobby Plan, begin at $9 per month for increased request volumes. The API provides a RESTful interface, returning data in JSON format, which is a common data interchange format for web services, as specified by the W3C JSON standard. This guide focuses on the immediate steps to make your first functional call.

Quick reference table

Create an account and get keys

To begin using Calendarific, you must first create an account. This process grants you access to the Calendarific dashboard, where your unique API key is generated and managed.

1. Navigate to the Pricing Page: Go to the Calendarific pricing page.
2. Select a Plan: Choose the 'Developer' plan, which is free and suitable for getting started, or any other plan that meets your requirements. Click the 'Get Started' or 'Sign Up' button associated with your chosen plan.
3. Complete Registration: Provide the necessary information (e.g., email address, password) to create your account. You may need to verify your email address.
4. Access Dashboard: Once registered and logged in, you will be directed to your Calendarific dashboard.
5. Locate API Key: On your dashboard, your API key will be prominently displayed. It is typically labeled as 'API Key' or 'Your API Key'. This key is a unique alphanumeric string that authenticates your requests. Keep this key secure, as it grants access to your Calendarific account's API usage. The Calendarific API documentation provides further details on key management.

Your first request

With your API key in hand, you can now make your first call to the Calendarific API. This example demonstrates how to retrieve public holidays for a specific country and year using the /holidays endpoint. We will use cURL for this demonstration, as it is a widely available command-line tool for making HTTP requests, as described in cURL's official documentation.

API Endpoint

The primary endpoint for retrieving holiday data is:

https://calendarific.com/api/v2/holidays

Required Parameters

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

Example Request (cURL)

Replace YOUR_API_KEY with your actual API key.

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

Example Response (JSON)

A successful request will return a JSON object containing holiday data. The structure will resemble the following (truncated for brevity):

{
  "meta": {
    "code": 200
  },
  "response": {
    "holidays": [
      {
        "name": "New Year's Day",
        "description": "New Year's Day is the first day of the calendar year...",
        "date": {
          "datetime": {
            "year": 2026,
            "month": 1,
            "day": 1
          },
          "iso": "2026-01-01"
        },
        "type": [
          "National holiday"
        ]
      },
      {
        "name": "Martin Luther King, Jr. Day",
        "description": "Birthday of Martin Luther King, Jr.",
        "date": {
          "datetime": {
            "year": 2026,
            "month": 1,
            "day": 19
          },
          "iso": "2026-01-19"
        },
        "type": [
          "National holiday"
        ]
      }
      // ... more holidays
    ]
  }
}

The meta.code: 200 indicates a successful API call. The response.holidays array contains objects, each representing a holiday with details such as name, description, and date.

Using other languages

Calendarific's API documentation also provides examples for making requests using various programming languages, including JavaScript, PHP, Python, Ruby, and Go. These examples typically involve using HTTP client libraries native to each language to construct and send the GET request, and then parsing the JSON response. For detailed code snippets in these languages, refer to the Calendarific API documentation.

Common next steps

After successfully making your first request, consider these common next steps to further integrate Calendarific into your application:

• Explore Additional Parameters: The /holidays endpoint supports optional parameters such as month, day, and language. For instance, you can specify &month=1 to retrieve holidays only for January, or &language=fr for French holiday names. Review the Calendarific API documentation for a complete list of available parameters and their usage.
• Error Handling: Implement robust error handling in your application. The API returns different HTTP status codes and error messages in the JSON response for issues like invalid API keys, rate limits, or bad requests. Understanding these error codes is crucial for building resilient integrations.
• Rate Limiting: Be aware of the rate limits associated with your Calendarific plan. Exceeding these limits will result in error responses. Implement strategies like request queuing or exponential backoff to manage your API calls effectively.
• Date Validation API: Calendarific also offers a Date Validation API. This endpoint allows you to check if a specific date is a holiday in a given country, which can be useful for scheduling and business logic.
• Integrate into Application Logic: Begin integrating the retrieved holiday data into your application's features. This could involve displaying holidays on a calendar, adjusting scheduling algorithms, or triggering specific events based on holiday occurrences.

Troubleshooting the first call

When making your first API call, you might encounter issues. Here are common problems and their solutions:

• Invalid API Key (HTTP 401 Unauthorized):
  • Problem: You receive an error indicating an unauthorized request or an invalid API key.
  • Solution: Double-check that you have copied your API key correctly from your Calendarific dashboard. Ensure there are no leading or trailing spaces, and that the key is correctly included as the api_key parameter in your request URL.
• Missing Required Parameters (HTTP 400 Bad Request):
  • Problem: The API returns an error stating that required parameters are missing.
  • Solution: Verify that you have included all mandatory parameters: api_key, country, and year. For example, ensure your URL includes &country=US&year=2026 in addition to your API key.
• Rate Limit Exceeded (HTTP 429 Too Many Requests):
  • Problem: You receive an error indicating that you have made too many requests.
  • Solution: If you are on the free Developer Plan, you are limited to 1,000 requests per month. Wait for your rate limit to reset, or consider upgrading your plan on the Calendarific pricing page for higher request volumes. For development, space out your requests.
• Incorrect Country Code:
  • Problem: The API returns no holidays or an error related to the country parameter.
  • Solution: Ensure you are using the correct ISO 3166-1 alpha-2 country code. For instance, use US for the United States, not USA. The Calendarific documentation lists supported country codes.
• Network Connectivity Issues:
  • Problem: Your request times out or fails with a network error.
  • Solution: Check your internet connection. If using cURL, ensure you have proper network access. If within a corporate network, check for proxy or firewall restrictions that might be blocking outbound API calls.