Public Holidays API
Query public holidays for 100+ countries and any year in a single API call. Fully local computation — no external data sources, no rate-limit surprises.
Don't have an API key?
Sign in to your account to create and manage your API keys.
API Integration Guide
Learn how to integrate this API into your applications with code examples and detailed documentation.
/api/holidaysBase URL
https://www.apipick.comFull Endpoint
https://www.apipick.com/api/holidayscountryISO 3166-1 alpha-2 country code
Example: USyear4-digit year (defaults to current year)
Example: 2026cURL Request
curl -X GET "https://www.apipick.com/api/holidays" \
-H "x-api-key: YOUR_API_KEY"YOUR_API_KEY with your actual API keyJSON Response
{
"success": true,
"code": 200,
"message": "Holidays retrieved successfully",
"data": {
"country": "US",
"country_name": "United States",
"year": 2026,
"total": 11,
"holidays": [
{
"date": "2026-01-01",
"name": "New Year's Day"
},
{
"date": "2026-01-19",
"name": "Martin Luther King Jr. Day"
},
{
"date": "2026-02-16",
"name": "Presidents' Day"
},
{
"date": "2026-05-25",
"name": "Memorial Day"
},
{
"date": "2026-07-03",
"name": "Independence Day (observed)"
},
{
"date": "2026-09-07",
"name": "Labor Day"
},
{
"date": "2026-10-12",
"name": "Columbus Day"
},
{
"date": "2026-11-11",
"name": "Veterans Day"
},
{
"date": "2026-11-26",
"name": "Thanksgiving Day"
},
{
"date": "2026-12-25",
"name": "Christmas Day"
}
]
},
"credits_used": 1,
"remaining_credits": 99
}✓Best Practices
- • Always include x-api-key header
- • Always handle errors gracefully
- • Validate input data before sending
- • Use HTTPS for secure communication
- • Cache responses when appropriate
ℹResponse Headers
- • Content-Type: application/json
- • x-api-key: Required for authentication
- • Status codes: 200 (success), 400 (error), 401 (unauthorized)
- • No rate limiting applied
Built for Real-World Scheduling
HR Scheduling
Automatically exclude public holidays when calculating leave balances, payroll cycles, and shift rosters across multiple countries.
Trading Calendars
Skip non-trading days in financial models and backtests. Identify bank holidays that affect settlement and clearing windows.
Logistics ETAs
Calculate accurate delivery estimates by skipping holidays in the origin, transit, and destination countries automatically.
n8n Automation
Wire into n8n or Zapier workflows to gate time-sensitive actions — skip sending emails or reports on national holidays.
HolidayAPI & Nager.Date Alternative
Current-year data, future-year planning, and a production SLA — without the free-tier year lock or community-project reliability risk.
HolidayAPI | Nager.Date | API Pick ✓ | |
|---|---|---|---|
| Free tier | Previous year only | Free (no SLA) | 100 credits on signup |
| Current year data | Paid plan only | ✓ | ✓ |
| Future year data | Paid plan only | ✓ (limited) | ✓ up to +10 years |
| Historical data (1900+) | Paid plan only | Partial | ✓ from 1900 |
| Production SLA | Paid plans only | ✗ Community project | ✓ |
| Countries covered | ~100 | ~110 | 100+ |
| No credit card to start | ✗ | ✓ | ✓ |
| Credits / requests expire? | Annual plan | N/A | Never expire |
| AI agent / LLM ready | Partial | Partial | ✓ Native JSON |
The HolidayAPI free-tier trap
HolidayAPI's free plan is intentionally limited to the previous calendar year only. Need to look up holidays for the current year or plan ahead for 2027 leave schedules? You must upgrade to a paid plan. For any scheduling or automation use case, this makes the free tier practically useless from day one.
The Nager.Date reliability risk
Nager.Date is a community-maintained open-source project — free to use but with no uptime SLA, no support contract, and no guarantee of continued availability. Teams that have built payroll systems or logistics pipelines on it have been caught out by unexpected downtime or deprecation. Fine for prototyping; not for production.
Response Fields
| Field | Type | Description |
|---|---|---|
| data.country | string | ISO 3166-1 alpha-2 country code (uppercase) |
| data.country_name | string | Full English name of the country |
| data.year | integer | The queried calendar year |
| data.total | integer | Number of public holidays in the year |
| data.holidays | array | List of holiday objects sorted by date |
| data.holidays[].date | string | Holiday date in YYYY-MM-DD format |
| data.holidays[].name | string | Official name of the holiday |
| credits_used | integer | Credits deducted for this request |
| remaining_credits | integer | Credits remaining in your account |
Frequently Asked Questions
Q: Which countries are supported?
A: 100+ countries via the open-source python-holidays (vacanza) library. This includes the US, UK, Germany, France, Japan, China, Australia, Canada, India, Brazil, and most of Europe, Asia, Latin America, and Africa. Use a valid ISO 3166-1 alpha-2 code (e.g. US, GB, DE).
Q: How far back and forward can I query?
A: You can query any year from 1900 up to 10 years in the future. Historical holidays are computed based on the rules that were in effect at the time, so results reflect actual historical observances rather than today's rules projected backwards.
Q: Are regional/state holidays included?
A: This endpoint returns national public holidays only. State-, province-, or region-specific observances (e.g. US state holidays, German Länder holidays) are not included in the default response. Contact us if you need subdivision-level holiday data.
Q: Can AI agents use this as a tool?
A: Yes. The endpoint takes two query parameters (country and year) and returns a structured JSON array — straightforward to define as a function tool for OpenAI, Claude, LangChain, or any agent framework. Ideal for scheduling agents that need to reason about working days across multiple countries.