11holidays

Global holidays API for public holidays, bank holidays and observances from 230+ countries. Use it over plain HTTP, through the npm package, or as free iCal feeds.

Installation

Contents

• Get an API key
• HTTP API
• npm package
• Free iCal feeds
• For AI agents and LLMs
• Free tools
• Support

Get an API key

The REST API needs an API key. Buy a key, and see pricing for the plans:

Plan	Price	Includes
Yearly	$99/year	Unlimited requests, all 230+ countries, historical data
Lifetime	$249 once	Everything in Yearly, paid once

HTTP API

• Base URL: https://api.11holidays.com/v1
• Authentication: Authorization: Bearer YOUR_API_KEY
• Reference: interactive API docs and the OpenAPI 3.0 spec

Method	Endpoint	Description
GET	/holidays?country={CODE}&year={YYYY}	Holidays for a country and year
GET	/holidays/{id}	A single holiday by id
GET	/countries	Supported countries
GET	/occasions	Holidays and festivals with descriptions

List holidays by country and year

curl "https://api.11holidays.com/v1/holidays?country=US&year=2026" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "holiday_id": 6093,
    "name": "New Year's Day",
    "date": "2026-01-01",
    "description": "...",
    "occasion_id": 6220,
    "country": "US",
    "type": "Federal Holiday",
    "created_at": "2025-10-28 15:10:10",
    "updated_at": null
  }
]

Parameter	Type	Required	Description
country	string	Yes	2 character ISO 3166-1 country code, e.g. US
year	integer	Yes	Year in 4 digit format, e.g. 2026

List countries

curl "https://api.11holidays.com/v1/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  { "country": "US", "name": "United States" },
  { "country": "IN", "name": "India" }
]

JavaScript (fetch)

const res = await fetch('https://api.11holidays.com/v1/holidays?country=GB&year=2026', {
  headers: { Authorization: `Bearer ${process.env.HOLIDAYS_API_KEY}` },
});
const holidays = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.11holidays.com/v1/holidays",
    params={"country": "IN", "year": 2026},
    headers={"Authorization": f"Bearer {os.environ['HOLIDAYS_API_KEY']}"},
)
holidays = res.json()

Errors

Errors return JSON with a message, for example { "message": "Invalid API Key" }.

Status	Meaning
400	Invalid query or path parameters
401	Missing or invalid API key
404	Holiday not found

npm package

npm i 11holidays

import HolidaysApi from '11holidays';

const instance = new HolidaysApi(process.env.HOLIDAYS_API_KEY);

// Holidays for a country and year
const holidays = await instance.holidays.list({ country: 'US', year: 2026 });

// A single holiday by id
const holiday = await instance.holidays.get(6093);

// Supported countries
const countries = await instance.countries.list();

Responses are the same JSON as the HTTP API.

Free iCal feeds

Subscribe to any country's holidays in Google Calendar, Outlook or Apple Calendar. No key needed.

https://11holidays.com/ics/{code}              # current and next year
https://11holidays.com/ics/{code}?year=2026    # one year
https://11holidays.com/ics/{code}?public=1     # public holidays only

For example https://11holidays.com/ics/us.

For AI agents and LLMs

11holidays is built to be read by AI agents as well as people:

• /llms.txt: a plain-text guide to every page, URL pattern, tool and API endpoint (llmstxt.org)
• /.well-known/api-catalog: RFC 9727 API discovery that links to the OpenAPI spec and docs
• OpenAPI 3.0 spec: import it as tools in an agent framework, a custom GPT action or an MCP gateway
• Link headers on every page (describedby, api-catalog, service-desc, service-doc), so agents can find the API from any URL
• Server-rendered HTML with schema.org JSON-LD (Event, ItemList, Dataset, FAQPage)
• robots.txt allows search and AI crawlers, with Content Signals ai-train=yes, search=yes, ai-input=yes

Free tools

• Holiday calendars: printable and embeddable holiday calendars
• Long weekends: plan trips around public holidays
• Leave planner: the most days off from your leave budget
• Working days calculator: business days between two dates, excluding holidays
• Countdown and embeddable widget
• All tools

Support

• If you have any question related to API key, access etc. contact support.
• Open an issue on Github for question related to SDK