
Get Public Holidays for a Date Range with One API Call
To get every public holiday between two dates, send one request with a start date and an end date. The API returns all matching holidays in a single response, so you do not need to make one call per day.
Range queries are available on the Premium plan and above. If you are on the Free or Basic plan, see the pricing guide to compare plans first.
The request
Use the start and end parameters together with a code for the country. Both dates are included in the range.
curl "https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=FR&start=01-01-2026&end=31-12-2026"
The default date format is DD-MM-YYYY. To use ISO dates, add format=YYYY-MM-DD:
curl "https://holidaysmap.com/api/v1/holidays?key=YOUR_API_KEY&code=FR&start=2026-01-01&end=2026-12-31&format=YYYY-MM-DD"
The response contains the number of holidays and the list:
{
"count": 2,
"holidays": [
{
"name": "New Year's Day",
"date": "2026-01-01",
"is_public": true,
"country": "France",
"country_code": "FR"
},
{
"name": "Labour Day",
"date": "2026-05-01",
"is_public": true,
"country": "France",
"country_code": "FR"
}
]
}
The response above is shortened for readability. A full year returns the complete list.
Use it in JavaScript
const params = new URLSearchParams({
key: process.env.HOLIDAYS_API_KEY,
code: 'FR',
start: '2026-01-01',
end: '2026-12-31',
format: 'YYYY-MM-DD',
});
const response = await fetch(`https://holidaysmap.com/api/v1/holidays?${params}`);
if (!response.ok) {
throw new Error(`Holidays request failed with status ${response.status}`);
}
const { holidays } = await response.json();
const publicHolidays = holidays.filter((holiday) => holiday.is_public);
Use it in Python
import os
import requests
response = requests.get(
"https://holidaysmap.com/api/v1/holidays",
params={
"key": os.environ["HOLIDAYS_API_KEY"],
"code": "FR",
"start": "2026-01-01",
"end": "2026-12-31",
"format": "YYYY-MM-DD",
},
timeout=10,
)
response.raise_for_status()
public_holidays = [h for h in response.json()["holidays"] if h["is_public"]]
Rules to remember
- Both dates are required. Sending
startwithoutend, or the other way round, returns an error. - Do not combine
datewith a range. Usedatefor one day andstartwithendfor a range. - The plan must be Premium or higher. Free and Basic plans get a 400 error that says the plan must be at least Premium.
- The range is inclusive. A holiday on the start date or the end date is included.
- Every holiday is listed. Observances marked
is_public: falseare returned too, so filter them out if you only want public holidays.
Caching a year
A range request is the cheapest way to build a yearly calendar, because it uses one call. Save the response, for example in your database or a cache keyed by country and year, and read from there. Public holidays for a finished year do not change, so a cached response can be used until your application needs a refresh.
If you need the working days between two dates instead of the holidays themselves, see how to calculate business days excluding public holidays.
Next steps
- Check the full parameter list in the API documentation.
- Find the country code you need on the supported countries page.
- See the response format guide for every field.