Holidays
Get a list of public holidays for any country and year. Useful for building calendar apps, scheduling, and compliance tools.
Vue d'ensemble
Cas d'utilisation
- Calendar applications
- Scheduling and booking systems
- Compliance and deadline tracking
- Travel and logistics planning
Fonctionnalités
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
Points de terminaison de l'API
Get Holidays
Returns a list of public holidays for the specified country and year
GET
https://requiems.xyz/v1/places/holidays
Paramètres
| Nom | Type | Requis | Description |
|---|---|---|---|
| country | string |
Requis | ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE") |
| year | integer |
Requis | Year for which to retrieve holidays (e.g., 2025) |
Essayez-le
Démo en directRequête
ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")
Year for which to retrieve holidays (e.g., 2025)
Sending request...
Champs de réponse
| Champ | Type | Description |
|---|---|---|
| country | string |
ISO 3166-1 alpha-2 country code |
| year | integer |
Year for which holidays are returned |
| holidays | array<object> |
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 |
Exemples de code
curl "https://requiems.xyz/v1/places/holidays?country=US&year=2025" \
-H "requiems-api-key: YOUR_API_KEY"import requests
url = "https://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://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://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']Réponses d'erreur
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://requiems.xyz/v1/places/holidays/batch
Paramètres
| Nom | Type | Requis | Description |
|---|---|---|---|
| queries | array<object> |
Requis | Array of (country, year) pairs. Min: 1, Max: 50. |
Essayez-le
Démo en directRequête
Array of (country, year) pairs. Min: 1, Max: 50.
Sending request...
Champs de réponse
| Champ | Type | Description |
|---|---|---|
| results | array<object> |
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<object> |
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) |
Exemples de code
curl -X POST "https://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://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://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`);
});Réponses d'erreur
bad_request
Malformed request body
validation_failed
queries is missing, empty, exceeds 50 items, or contains invalid country codes or years
Foire aux 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.