[ reference · holidays ]● 1 cr · 120 req/min

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.

100+ countriesAny yearNo external deps

auth · x-api-key

API Key

Don't have an API key?

[ 02 · integrate ]

Integration guide

Copy a snippet, replace your API key, run. Works in any HTTP client — examples below in cURL, JavaScript, and Python.

spec

GET/api/holidays

base

https://www.apipick.com

Get all public holidays for a country and year

parameters

countrystringrequired

ISO 3166-1 alpha-2 country code US

yearintegeroptional

4-digit year (defaults to current year) 2026

curl -X GET "https://www.apipick.com/api/holidays" \
  -H "x-api-key: YOUR_API_KEY"

● 200 · 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
}

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

[ 03 · limits ]

Rate limits

Throttling is per API key, sliding 60-second window. Hit the limit and you get a clean 429 with a Retry-After header.

request rate

120req/min

Per API key, per endpoint. Sliding 60-second window.

concurrency

3concurrent

Max simultaneous in-flight requests per API key.

response headers

X-RateLimit-LimitMaximum requests allowed per minute

X-RateLimit-RemainingRequests remaining in the current window

X-RateLimit-ResetSeconds until the current window resets

Retry-AfterSeconds to wait before retrying (only on 429)

● 429 · too many requests

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 120 requests/minute per API key. Retry after 12s.",
  "retry_after": 12
}

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.

🤖Agent Skill

Use Public Holidays in Claude Code & AI Agents

Install the official Claude Code skill to query public holidays for 100+ countries directly inside your AI coding agent — sorted dates, official names, and counts via natural language.

Ask your AI agent naturally

›What are the US public holidays in 2026?

›List all public holidays in Japan for this year

›Is December 26 a holiday in the UK?

Compatible platforms

Claude CodeCursorOpenAI CodexManusGoogle AntigravityOpenClaw

apipick-lab /

apipick-public-holidays

Claude Code skill for APIpick Public Holidays API

Returns holiday lists sorted by date with official English names and total counts for 100+ countries. Supports years from 1900 to 10 years ahead.

TypeScript•1 credit / request•Free to install

View Skill on GitHub