How do I specify which country's holidays I want?
Use the country parameter with ISO2 codes (US), ISO3 codes (USA), or full names (United States), and comma-separate multiple values to merge calendars. If omitted, the API defaults to US.
Public Holidays API
Multi-Country
JSON + CSV
Date-Range Filters
Public holidays. Any country.
Query holiday calendars by ISO2, ISO3, or full country name. Filter by year, month, or date range, and export straight to CSV for reporting.
multi · countries per call3 · date formats per rowISO2 / ISO3 / name · country inputJSON + CSV · output
Pull a holiday calendar.
This calls the live Public Holidays API. Pick countries and a period; the response includes US, EU, and ISO date formats for every holiday.
Request builder
Countries and period in, holiday rows out.
GET /public-holidays
Production also accepts ISO3 codes and full names, e.g. USA or United States.
CSV export built in
Add format=csv to the same query to download rows for spreadsheets and reporting. The demo shows JSON; the CSV columns match one to one.
Output preview
Live response from the API, plus the exact request to reproduce it.
| date | holiday | country |
|---|---|---|
| Loading live response... | ||
Why Public Holidays API
Holiday calendars without the maintenance.
Flexible country input
Pass ISO2 codes, ISO3 codes, or full country names, in any mix. US, USA, and United States all resolve to the same calendar.
Multi-country queries
Comma-separate countries to merge calendars in one request, ideal for teams and payroll spanning several regions.
Year, month, and range filters
Filter by year, narrow to a single month, or use start_date and end_date for exact windows like a fiscal quarter.
Three date formats per row
Every holiday includes date_us_format, date_eu_format, and date_iso_format, so no locale reformatting is needed downstream.
CSV export
Set format=csv on the same query to get an export-ready file for spreadsheets, BI tools, and reporting workflows.
Country metadata endpoint
GET /countries lists every supported country with ISO2, ISO3, and numeric codes for building pickers and validation.
/api/v1/public-holidays
Endpoints, at a glance.
One query endpoint with country and period filters, plus a countries metadata endpoint. All read-only GETs.
GET/api/v1/public-holidays
Query holidays
Holiday rows for one or more countries, filtered by year, month, or explicit date range. JSON by default, CSV via format=csv.
GET/countries
Supported countries
Country metadata with ISO2 code, name, ISO3 code, and numeric code for building pickers.
GET/health
Service health
Status, service name, version, timestamp, and uptime.
GET/metrics
Prometheus metrics
Request counts and latency histograms in Prometheus exposition format.
| Parameter | Type | Required | Description |
|---|---|---|---|
| country | string | no | Country selector: ISO2, ISO3, full names, or comma-separated combinations. Defaults to US. |
| year | integer | no | Year filter, e.g. 2026. |
| month | integer | no | Month filter (1 to 12), used together with year. |
| start_date / end_date | string | no | Explicit date-range filter in YYYY-MM-DD format, as an alternative to year and month. |
| format | string | no | "json" (default) or "csv" for an export-ready file with the same columns. |
Error reference
Clear errors with guidance.
Failures return an error, an optional message with fix hints, and a correlationId.
400Validation Error
No valid countries resolved from the country input. Provide ISO2 codes (US), ISO3 codes (USA), or full names (United States).
401Authentication Error
Missing or invalid API key at the gateway. Send x-api-key or api_key with every request.
404No Holidays Found
CSV was requested but the query matched zero holiday rows. Widen the filters and retry.
504Query Timeout
The holiday query exceeded 30 seconds. Narrow the country list or date range and retry.
500Internal Error
Query or processing failure. Include the correlationId when reporting the issue.
Example error response
{
"error": "No valid countries found",
"message": "Please provide valid ISO2 codes (US), ISO3 codes (USA), or full country names (United States)",
"correlationId": "req-abc123"
}FAQ
API questions developers ask first.
Can I query holidays for several countries at once?
Yes. country=US,CA returns both calendars in one response, with each row labeled by country code and country name so you can group results downstream.
What date formats are included in responses?
Every holiday row carries date_us_format (MM/DD/YYYY), date_eu_format (DD/MM/YYYY), and date_iso_format (YYYY-MM-DD), plus the raw timestamp, so no locale conversion is needed.
How do I export holidays to a spreadsheet?
Add format=csv to any query. The API returns a CSV file with the same columns as the JSON response, ready for Excel, Google Sheets, or BI tools. If the query matches no rows, CSV requests return a 404.
How do I authenticate requests?
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Know every holiday before it lands.
Query holiday calendars by country and period, get three date formats per row, and export CSV for reporting. No calendar files to maintain.