English

Holiday API

Free JSON API for public holiday data. 199 countries, 6 languages, 2024-2030. No API key required.

Endpoints

GET /api/v1/holidays

Get public holidays for a specific country and year.

Parameters

ParameterRequiredDescription
countryYesISO 3166-1 alpha-2 country code (e.g., TR, US, DE)
yearYesYear between 2024-2030
typeNoFilter by type: public, bank, observance, religious
langNoLanguage: en, tr, de, es, fr, pt (default: en)

Example

https://holidaycalendar.pages.dev/api/v1/holidays?country=TR&year=2026&lang=tr

Response

{
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "Yılbaşı",
      "type": "public"
    },
    {
      "date": "2026-03-19",
      "name": "Ramazan Bayramı Arifesi",
      "type": "public"
    }
  ],
  "meta": {
    "country": "TR",
    "year": 2026,
    "total": 16,
    "types": { "public": 16 }
  }
}
GET /api/v1/countries

List all supported countries with codes, names, and continent.

Parameters

ParameterRequiredDescription
langNoLanguage for country names (default: en)

Example

https://holidaycalendar.pages.dev/api/v1/countries?lang=en
GET /api/v1/calendar/[country].ics

Download an ICS calendar file for a country. Use as a subscription URL in calendar apps.

Parameters

ParameterRequiredDescription
yearNoYear (default: current year)
langNoLanguage for holiday names (default: en)

Example

https://holidaycalendar.pages.dev/api/v1/calendar/TR.ics?year=2026&lang=tr

Quick Start

1
No setup needed

No API key, no sign-up. Just send an HTTP GET request.

2
JavaScript example 
const res = await fetch(
  'https://holidaycalendar.pages.dev/api/v1/holidays?country=US&year=2026'
);
const data = await res.json();
console.log(data.holidays);
3
Python example 
import requests
r = requests.get(
  'https://holidaycalendar.pages.dev/api/v1/holidays',
  params={'country': 'US', 'year': 2026}
)
holidays = r.json()['holidays']

Details

Response Format

All endpoints return JSON with UTF-8 encoding. ICS endpoint returns text/calendar.

Caching

Responses include Cache-Control headers (24h). Holiday data rarely changes within a year.

CORS

Cross-origin requests are supported. Call the API directly from browser JavaScript.

Rate Limits

No hard rate limits for reasonable use. Please cache responses on your end for high-traffic apps.

Frequently Asked Questions

Is the API free?

Yes. Completely free with no API key, no registration, and no usage limits for reasonable use.

What data formats are available?

JSON for the holidays and countries endpoints, ICS (iCalendar) for calendar feeds. All text is UTF-8 encoded.

How many countries are supported?

199 countries and territories across 6 continents, with data from 2024 through 2030.

Can I use it in commercial projects?

Yes. The API is free for both personal and commercial use. We appreciate a link back but it is not required.

Is there a rate limit?

No hard rate limit, but please cache responses for high-traffic applications. Responses include a 24-hour Cache-Control header.