Public Holidays API docs
Official public holidays for 100+ countries — all holidays for a given year, the next upcoming holidays, and the full list of supported countries.
Authentication
All Public Holidays API requests authenticate via two headers. Get your API key from your RapidAPI dashboard after subscribing on the Basic (free) tier or higher.
X-RapidAPI-Key: YOUR_API_KEY X-RapidAPI-Host: public-holidays-by-helix-api.p.rapidapi.com
Base URL
https://public-holidays-by-helix-api.p.rapidapi.com
Endpoints
GET
/holidaysAll public holidays for a country and year
GET
/nextUpcoming holidays for a country (next 365 days)
GET
/countriesList all supported countries
Code Examples
Python
import requests
url = "https://public-holidays-by-helix-api.p.rapidapi.com/holidays"
headers = {
"X-RapidAPI-Key": "YOUR_API_KEY",
"X-RapidAPI-Host": "public-holidays-by-helix-api.p.rapidapi.com",
}
response = requests.get(url, headers=headers)
print(response.json())JavaScript
const response = await fetch(
"https://public-holidays-by-helix-api.p.rapidapi.com/holidays",
{
method: "GET",
headers: {
"X-RapidAPI-Key": "YOUR_API_KEY",
"X-RapidAPI-Host": "public-holidays-by-helix-api.p.rapidapi.com"
}
}
);
const data = await response.json();cURL
curl -X GET "https://public-holidays-by-helix-api.p.rapidapi.com/holidays" \ -H "X-RapidAPI-Key: YOUR_API_KEY" \ -H "X-RapidAPI-Host: public-holidays-by-helix-api.p.rapidapi.com"
Response Format
All endpoints return JSON in this consistent envelope:
{
"status": "ok",
"data": { /* endpoint-specific payload */ },
"meta": {
"cached": false,
"latency_ms": 142,
"request_id": "req_abc123"
},
"timestamp": "2026-05-21T12:00:00Z"
}Error Codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | Missing or invalid parameter |
| 401 | UNAUTHORIZED | Invalid or missing API key |
| 403 | FORBIDDEN | Your plan doesn't include this endpoint |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests — back off and retry |
| 500 | INTERNAL_ERROR | Something went wrong on our side |
| 503 | UPSTREAM_UNAVAILABLE | A third-party data source is down |
Common Use Cases
HR & payroll systems
Scheduling apps
Trading platforms
Travel booking
Calendar integrations
Shipping deadline calculator
Customer support SLA planning
School year calendar builder
Marketing campaign timing
Restaurant holiday hours
Retail sale date planning
Government office closure alerts
International meeting scheduler
Leave management system
E-commerce shipping cutoff dates
Invoice due date adjustment
Employee onboarding timeline
Cross-border compliance deadlines
Subscription renewal timing
Event venue availability checker