Public Holidays API
FreemiumPublic holidays for 150+ countries — including Indian states — plus 'is it a holiday?', upcoming holidays and working-day counts.
Documentation
Public holidays for 150+ countries.
What you get
- Holidays for 150+ countries and their states/provinces, including Indian states
- Is today a holiday? for any date
- Next holidays from any date
- Working days between two dates, excluding weekends and holidays
Great for HR and payroll, scheduling, delivery-date estimates, travel and calendar apps.
Quick start
Subscribe to a plan (the Basic plan is free), then call the API at https://public-holidays.p.apihiver.com with your key in the X-API-Key header:
curl "https://public-holidays.p.apihiver.com/v1/holidays?country=IN&subdivision=MH" \
-H "X-API-Key: YOUR_API_KEY"Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/holidays | All public holidays for a country and year |
GET | /v1/is-holiday | Is a date a public holiday (and is it a weekend)? |
GET | /v1/next | Upcoming public holidays from a date |
GET | /v1/working-days | Count working days between two dates (skips weekends and holidays) |
GET | /v1/countries | Supported countries and their state/region codes |
Open the Endpoints tab to see every parameter, example request and example response, and to try the API live.
Errors
Every error is JSON with the same shape:
{"error": {"code": "INVALID_INPUT", "message": "country: Field required"}}| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_INPUT | A parameter is missing or has the wrong format — the message says which |
| 401 | UNAUTHORIZED | Missing or invalid X-API-Key |
| 429 | — | Plan quota or rate limit reached (see the X-RateLimit-* headers) |
| 502 / 503 / 504 | — | A data source or the API server is temporarily unavailable — retry after a few seconds |
Data & privacy
Data comes from the python-holidays library (MIT), computed on our servers.
Public Holidays API FAQ
- Is the Public Holidays API free?
- Yes. The Basic plan is free and includes 500 requests per month — no card needed. Paid plans start at ₹299 per month for 10,000 requests.
- How much does the Public Holidays API cost?
- Basic: free for 500 requests; Pro: ₹299/month for 10,000 requests; Ultra: ₹999/month for 50,000 requests; Mega: ₹2,499/month for 2,00,000 requests. Billing is monthly and you can cancel any time.
- How do I use the Public Holidays API?
- Subscribe to a plan on APIHiver, create an API key in the Console, then send requests to https://public-holidays.p.apihiver.com with your key in the X-API-Key header. You can also try every endpoint in the browser playground first.
- What endpoints does the Public Holidays API have?
- It has 5 endpoints: All public holidays for a country and year (GET /v1/holidays); Is a date a public holiday (and is it a weekend)? (GET /v1/is-holiday); Upcoming public holidays from a date (GET /v1/next); Count working days between two dates (skips weekends and holidays) (GET /v1/working-days); Supported countries and their state/region codes (GET /v1/countries).
- What are the Public Holidays API rate limits?
- Basic: 2 requests per second; Pro: 5 requests per second; Ultra: 10 requests per second; Mega: 20 requests per second. Monthly quotas depend on the plan; every response includes X-RateLimit headers showing what's left.
- Can I use one API key for the Public Holidays API and other APIs?
- Yes. One APIHiver key works for every API you subscribe to, so you don't need a separate account or key per provider.
Related APIs
Look up airports and airlines worldwide by IATA/ICAO code or name — location, type, elevation, country, call sign and more.
Search universities in 200+ countries, look up a university by web domain, and verify student email addresses.
Create QR codes for links, text, UPI payments, Wi-Fi logins and contact cards (PNG/SVG, custom colours) and read QR codes from images.
English definitions, synonyms, antonyms, rhymes, 'words that mean…' and autocomplete — fast and fully offline.
Search Wikipedia in 300+ languages, get article summaries with images, 'on this day' events, random articles and autocomplete.
Extract text from images and scans in English, Hindi and Marathi, and pull out emails, phone numbers, URLs, PAN and GSTIN.
Endpoints
5 endpoints — full list is in the sidebar on larger screens.