M
API Matrix

Holidays API

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

Overview

Holiday API (holidayapi.com) provides historical and current public holiday data for over 100 countries, dating back to 2015. It supports filtering by country, year, month, day, and holiday type, and includes multi-language names for holidays. A free account grants API access but with a one-year data lag — current-year data requires a paid plan.

💡

Beginner Tip

The free plan only returns data for years prior to last year. Test with a past year first (e.g., &year=2022) to confirm your key works before considering an upgrade for current-year data.

Available Data

event dates and names
holiday lists by country
date metadata

Example Response

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

Field Reference

holidays[].name Official English name of the holiday.
holidays[].date Actual date of the holiday in YYYY-MM-DD format.
holidays[].observed The date the holiday is officially observed, which can differ from the actual date when it falls on a weekend.
holidays[].public True if the holiday is a nationally recognized public holiday.
holidays[].country ISO country code indicating which country this holiday belongs to.
holidays[].uuid Unique identifier for this holiday entry in the Holiday API database.

Implementation Example 

const url = "https://holidayapi.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 API key not provided or passed with the wrong parameter name
✓ Use ?key=YOUR_KEY (not api_key or apikey) as the query parameter name.
402 Payment Required Requesting current-year data on the free plan
✓ The free tier only covers years at least two years in the past. Use year=2022 or earlier to test without a paid plan.
Empty holidays array for a valid country Country code passed in lowercase
✓ Country codes must be uppercase ISO 3166-1 alpha-2 format (e.g., US, CA, AU). The API is case-sensitive.

Matrix Score Breakdown

🌐 Reachability 30/30
⚡ Speed 15/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 →

Calendarific

72

Calendarific is a REST API that returns public holidays for over 230 countries and territories, supporting both Gregorian and non-Gregorian calendars.

API Key Intermediate HTTPS

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

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