Holidays
Get a list of public holidays for any country and year. Useful for building calendar apps, scheduling, and compliance tools.
Overview
Use Cases
- Calendar applications
- Scheduling and booking systems
- Compliance and deadline tracking
- Travel and logistics planning
Features
Support for 190+ countries
National and public holidays
Yearly calendar data
Fast response times
Batch endpoint for up to 50 (country, year) pairs per request
API Endpoints
Get Holidays
Returns a list of public holidays for the specified country and year
GET
https://api.requiems.xyz/v1/places/holidays
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| country | string |
Required | ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE") |
| year | integer |
Required | Year for which to retrieve holidays (e.g., 2025) |
Try it out
Live DemoRequest
ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")
Year for which to retrieve holidays (e.g., 2025)
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| country | string |
ISO 3166-1 alpha-2 country code |
| year | integer |
Year for which holidays are returned |
| holidays | array |
Array of holiday objects |
| holidays[].date | string |
Holiday date in YYYY-MM-DD format |
| holidays[].name | string |
Name of the holiday |
| total | integer |
Total number of holidays for the country/year |
Code Examples
curl "https://api.requiems.xyz/v1/places/holidays?country=US&year=2025" \
-H "requiems-api-key: YOUR_API_KEY"import requests
url = "https://api.requiems.xyz/v1/places/holidays"
params = {"country": "US", "year": 2025}
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, headers=headers, params=params)
print(response.json())const response = await fetch('https://api.requiems.xyz/v1/places/holidays?country=US&year=2025', {
headers: {
'requiems-api-key': 'YOUR_API_KEY'
}
});
const data = await response.json();
console.log(data.data.holidays);require 'net/http'
require 'json'
uri = URI('https://api.requiems.xyz/v1/places/holidays')
uri.query = URI.encode_www_form(country: 'US', year: 2025)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts data['data']['holidays']Error Responses
bad_request
Missing or invalid country code or year parameter
not_found
No holidays found for the specified country and year
Batch Get Holidays
Returns holidays for up to 50 (country, year) pairs in a single request. Each pair is processed independently โ if one combination has no data, it returns found:false without failing the entire batch.
POST
https://api.requiems.xyz/v1/places/holidays/batch
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| queries | array |
Required | Array of (country, year) pairs. Min: 1, Max: 50. |
Try it out
Live DemoRequest
Enter JSON array, e.g., [{"country":"US","year":2025},{"country":"AR","year":2024}]
Array of (country, year) pairs. Min: 1, Max: 50.
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| results | array |
One result per query, in the same order as the request |
| results[].country | string |
ISO 3166-1 alpha-2 country code |
| results[].year | integer |
Year queried |
| results[].found | boolean |
false when no holidays exist for that country/year combination |
| results[].holidays | array |
List of holidays. Omitted when found is false. |
| results[].total | integer |
Number of holidays. Omitted when found is false. |
| total | integer |
Total number of results (equals the number of queries sent) |
Code Examples
curl -X POST "https://api.requiems.xyz/v1/places/holidays/batch" \
-H "requiems-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"queries":[{"country":"US","year":2025},{"country":"AR","year":2024}]}'import requests
url = "https://api.requiems.xyz/v1/places/holidays/batch"
headers = {"requiems-api-key": "YOUR_API_KEY"}
body = {
"queries": [
{"country": "US", "year": 2025},
{"country": "AR", "year": 2024},
]
}
response = requests.post(url, headers=headers, json=body)
for result in response.json()["data"]["results"]:
if result["found"]:
print(f"{result['country']} {result['year']}: {result['total']} holidays")
else:
print(f"{result['country']} {result['year']}: not found")const response = await fetch('https://api.requiems.xyz/v1/places/holidays/batch', {
method: 'POST',
headers: {
'requiems-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
queries: [
{ country: 'US', year: 2025 },
{ country: 'AR', year: 2024 }
]
})
});
const { data } = await response.json();
data.results.forEach(r => {
if (r.found) console.log(`${r.country} ${r.year}: ${r.total} holidays`);
else console.log(`${r.country} ${r.year}: not found`);
});Error Responses
bad_request
Malformed request body
validation_failed
queries is missing, empty, exceeds 50 items, or contains invalid country codes or years
Frequently Asked Questions
The API supports holidays for over 190 countries using ISO 3166-1 alpha-2 country codes. This includes all UN member states plus many territories and dependencies.
The API returns national and public holidays for each country, including federal holidays, bank holidays, and widely observed holidays. Religious and regional holidays may vary by country.
Yes. Use the batch endpoint (POST /v1/places/holidays/batch) to query up to 50 (country, year) combinations in a single request. Each pair is resolved independently, so a missing combination returns found:false without affecting the rest of the results.