Paraguay Holiday API
Paraguay distinguishes between feriados inamovibles (fixed to a specific date, never transferred) and feriados puente (can be moved to the nearest Monday). May contains two consecutive independence holidays. A static list will be wrong the moment any puente is decreed.
Free plan includes commercial use · no credit card required
Why Paraguay's calendar can't be hardcoded
Paraguay's holiday system combines fixed civic dates, moveable puentes, and multi-day independence clusters that create gaps no generic calendar library handles correctly.
Some holidays are fixed forever to their date (Día de los Héroes, Mar 1). Others can be moved to the nearest Monday by executive decree. The API reflects the current year's official calendar, not a static rule.
Paraguay's independence spans two consecutive days: May 14 (Independencia) and May 15 (Día de la Patria). In 2026 both fall mid-week — a 2-day hole in any SLA or delivery window.
August 15 (Fundación de Asunción) and the nearby civic calendar create an August cluster. Combine with Aug 25 (Batalla de Boquerón) and you can have two non-working days in the same month close together.
API response for Paraguay
The May independence cluster — two consecutive national holidays — is the most common source of off-by-one errors in systems serving Paraguay.
{
"success": true,
"data": [
{
"date": "2026-03-01",
"name": "Día de los Héroes",
"type": "national"
},
{
"date": "2026-05-14",
"name": "Independencia Nacional",
"type": "national"
},
{
"date": "2026-05-15",
"name": "Día de la Patria",
"type": "national"
},
{
"date": "2026-08-15",
"name": "Fundación de Asunción",
"type": "national"
}
],
"meta": { "country": "PY", "year": 2026, "total": 13 }
}{
"success": true,
"data": {
"date": "2026-05-14",
"is_business_day": false,
"holiday_name": "Independencia Nacional"
},
"meta": { "country": "PY" }
}Endpoints for Paraguay
Replace :country with PY.
Free plan includes holidays, is-business-day, and next-holiday.
/v1/PY/holidays/:year Free All public holidays for Paraguay in a given year. Reflects the official calendar including any puente decrees.
"total": 13, "name": "Día de los Héroes" /v1/PY/is-business-day?date=YYYY-MM-DD Free Check if a date is a business day in Paraguay. Returns holiday name if applicable.
"is_business_day": false, "holiday_name": "Independencia Nacional" /v1/PY/business-days/add?date=YYYY-MM-DD&days=N Starter Add N business days to a date, skipping weekends and Paraguayan holidays including the May cluster.
"result_date": "2026-05-19" /v1/PY/business-days/between?from=YYYY-MM-DD&to=YYYY-MM-DD Starter Count business days between two dates, excluding Paraguayan holidays.
"business_days": 17 /v1/PY/last-business-day?date=YYYY-MM-DD Starter Get the last business day of the month. Essential for payroll cutoffs in Paraguay.
"last_business_day": "2026-05-29" Calculating SLA deadlines through May in Paraguay
The two consecutive independence holidays in May are the most common source of SLA breaches for systems serving Paraguay. This pattern calculates business-day deadlines correctly.
const API = "https://api.feriados.io/v1";
const KEY = process.env.FERIADOS_API_KEY;
async function getParaguaySLADeadline(startDate, businessDays) {
const res = await fetch(
`${API}/PY/business-days/add?date=${startDate}&days=${businessDays}`,
{ headers: { Authorization: `Bearer ${KEY}` } }
);
const { data } = await res.json();
return data.result_date;
}
// 5 business days from May 13 → skips May 14 + 15 (independence cluster)
const deadline = await getParaguaySLADeadline("2026-05-13", 5);
// → "2026-05-20" (not May 18 as a naive calculator would return)Common use cases for Paraguay
The same API key works for all 11 LATAM countries — Paraguay is just the country code.
A payment scheduled on May 14 or 15 hits back-to-back holidays. Paraguayan banks don't process on either day — reschedule automatically.
is-business-day Free "3 business days" starting May 13 means delivery arrives May 20, not May 18. The May cluster adds 2 extra calendar days.
business-days/add Starter Payroll periods in Paraguay that span the May cluster or the August holidays need exact worked-day counts.
business-days/between Starter Legal deadlines in Paraguay are measured in business days. Día de los Héroes (Mar 1) is inamovible — always a non-working day regardless of what day it falls on.
business-days/between Starter High-risk months for Paraguay in 2026
These are the months where date calculation bugs are most likely to surface in production.
Día de los Héroes (Mar 1, Sun in 2026) — inamovible, no transfer. Semana Santa also lands in late March/early April.
Viernes Santo (Apr 3) + Sábado Santo (Apr 4) — Semana Santa creates a 4-day weekend with Easter Sunday.
Independence cluster: May 14 (Thu) + May 15 (Fri) in 2026 — two consecutive holidays creating a 4-day weekend with the following Saturday.
Fundación de Asunción (Aug 15, Sat in 2026). Observed on Fri Aug 14 — affects payroll and billing cutoffs.
Also available for 10 more LATAM countries
Same API, same endpoints — just swap the country code.
Ready for production
Free API key in 30 seconds. Free plan includes is-business-day for Paraguay with commercial use.
Starter plan from $9/mo for full operational logic.