M
API Matrix

Calendarific API

Calendar / API Key Intermediate HTTPS
Varies by plan (check documentation)
72 Score
Grade B
Visit Official Site Compare Alternatives

Overview

Calendarific is a REST API that returns public holidays for over 230 countries and territories, supporting both Gregorian and non-Gregorian calendars. It accepts a country code, year, and optional month parameter to return structured holiday data including holiday type (national, local, religious). An API key is required and obtained by signing up on their website.

💡

Beginner Tip

Start with the free tier, which provides 1,000 requests/month. Pass your API key as a query parameter: ?api_key=YOUR_KEY&country=US&year=2024.

Available Data

event dates and names
holiday lists by country
date metadata
Use case: Integrate worldwide holidays data into web and mobile applications

Example Response

JSON Response 
{
  "status": "success",
  "data": {
    "result": "Data from Calendarific",
    "description": "Worldwide Holidays",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

Field Reference

response.holidays[].name Official name of the holiday, e.g., "Christmas Day".
response.holidays[].description Short description of the holiday's origin or significance.
response.holidays[].date.iso ISO 8601 date string of the holiday, e.g., "2024-12-25".
response.holidays[].type List of holiday types such as "National holiday", "Local holiday", or "Religious holiday".
response.holidays[].locations Applicable locations within the country; "All" means the holiday is nationwide.

Implementation Example 

const url = "https://calendarific.com/";
// Replace headers or query params with the values required by this API.
const response = await fetch(url, {
  headers: {
  "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

401 Unauthorized Missing or invalid api_key query parameter
✓ Ensure you append ?api_key=YOUR_KEY to every request; do not put it in the request body.
Empty response / no holidays returned Invalid country code or unsupported year range
✓ Use ISO 3166-1 alpha-2 country codes (e.g., US, GB, JP) and years between 2010 and 2049.
429 Too Many Requests Exceeded the monthly request quota for your plan
✓ Cache responses locally; one call per country/year combination is sufficient for a whole year of data.

Matrix Score Breakdown

🌐 Reachability 30/30
⚡ Speed 5/20
🔒 Security 15/15
🛠 Developer XP 12/20
✓ Reliability 10/15

Partially tested on Apr 5, 2026

Technical Specifications

Auth API Key
HTTPS REQUIRED
CORS UNKNOWN
Category Calendar
Difficulty Intermediate
Verified: 2026-04-04

Similar APIs

View All →

Checkiday - National Holiday API

77

Checkiday is a holiday data API covering more than 5,000 national days and observances in the United States, including unofficial holidays like National Pizza Day.

API Key Intermediate HTTPS

Festivo Public Holidays

82

Festivo is a public holidays API covering more than 60 countries with regional subdivision support, providing both national and state/province-level holidays.

API Key Intermediate HTTPS

Holidays

82

Holiday API (holidayapi.com) provides historical and current public holiday data for over 100 countries, dating back to 2015.

API Key Intermediate HTTPS

Public Holidays

92

Abstract's Public Holidays API delivers structured data about national, regional, and religious holidays for countries worldwide.

API Key Intermediate HTTPS

Church Calendar

⭐ Beginner's Pick
37

Church Calendar (calapi.inadiutorium.cz) is a free, no-auth REST API that returns the Roman Catholic liturgical calendar for any date or month.

No Auth Beginner 291ms