Holidays
Get a list of public holidays for any country and year. Useful for building calendar apps, scheduling, and compliance tools.
Descripción general
Casos de uso
- Calendar applications
- Scheduling and booking systems
- Compliance and deadline tracking
- Travel and logistics planning
Funcionalidades
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
Puntos finales de la API
Get Holidays
Returns a list of public holidays for the specified country and year
GET
https://requiems.xyz/v1/places/holidays
Parámetros
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| country | string |
Obligatorio | ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE") |
| year | integer |
Obligatorio | Year for which to retrieve holidays (e.g., 2025) |
Pruébalo
Demostración en vivoSolicitud
ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")
Year for which to retrieve holidays (e.g., 2025)
Sending request...
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| 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 |
Ejemplos de código
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']Respuestas de error
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
Parámetros
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| queries | array<object> |
Obligatorio | Array of (country, year) pairs. Min: 1, Max: 50. |
Pruébalo
Demostración en vivoSolicitud
Array of (country, year) pairs. Min: 1, Max: 50.
Sending request...
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| 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) |
Ejemplos de código
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`);
});Respuestas de error
bad_request
Malformed request body
validation_failed
queries is missing, empty, exceeds 50 items, or contains invalid country codes or years
Preguntas frecuentes
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.