Costa Rica Holiday API
Costa Rica distinguishes between full national holidays and días de asueto — partial closures that affect government and banking but not all commerce. Semana Santa is heavily observed, and April has two separate non-working dates within the same week. A generic calendar won't reflect these distinctions.
Free plan includes commercial use · no credit card required
Why Costa Rica's calendar can't be hardcoded
Costa Rica's holiday system has unique quirks around April, religious observances, and regional civic dates that generic holiday libraries routinely miss.
April has both Juan Santamaría Day (Apr 11) and Semana Santa (Viernes Santo). In some years these are within the same week — creating a stretch where multiple business days are lost. Most systems only model one of them.
In Costa Rica, Semana Santa is among the most observed in Central America. Most retail, logistics, and government operations shut down Thursday through Sunday. The official holiday is Viernes Santo, but the effective closure is 4 days.
The annexation of Guanacaste is an official national holiday with no equivalent in other LATAM countries. Any system that assumes July has no country-specific holidays will miss it for Costa Rica.
API response for Costa Rica
April 2026 shows both official holidays in the same month — Juan Santamaría and Semana Santa, 8 days apart.
{
"success": true,
"data": [
{
"date": "2026-04-03",
"name": "Viernes Santo",
"type": "national"
},
{
"date": "2026-04-11",
"name": "Día de Juan Santamaría",
"type": "national"
},
{
"date": "2026-07-25",
"name": "Anexión del Partido de Nicoya",
"type": "national"
},
{
"date": "2026-09-15",
"name": "Día de la Independencia",
"type": "national"
}
],
"meta": { "country": "CR", "year": 2026, "total": 13 }
}{
"success": true,
"data": {
"date": "2026-04-11",
"is_business_day": false,
"holiday_name": "Día de Juan Santamaría"
},
"meta": { "country": "CR" }
}Endpoints for Costa Rica
Replace :country with CR.
Free plan includes holidays, is-business-day, and next-holiday.
/v1/CR/holidays/:year Free All public holidays for Costa Rica in a given year. Includes both Juan Santamaría and the Guanacaste annexation.
"total": 13, "name": "Día de Juan Santamaría" /v1/CR/is-business-day?date=YYYY-MM-DD Free Check if a date is a business day in Costa Rica. Returns holiday name if applicable.
"is_business_day": false, "holiday_name": "Día de Juan Santamaría" /v1/CR/business-days/add?date=YYYY-MM-DD&days=N Starter Add N business days to a date, skipping weekends and Costa Rican holidays.
"result_date": "2026-04-14" /v1/CR/business-days/between?from=YYYY-MM-DD&to=YYYY-MM-DD Starter Count business days between two dates, excluding Costa Rican holidays.
"business_days": 19 /v1/CR/last-business-day?date=YYYY-MM-DD Starter Get the last business day of the month for the given date. Used for billing cycles and payroll cutoffs.
"last_business_day": "2026-04-30" Scheduling HR deadlines around Costa Rica's April window
April 2026 has two non-working days 8 days apart. This pattern calculates the exact number of working days in a payroll period that spans both.
const API = "https://api.feriados.io/v1";
const KEY = process.env.FERIADOS_API_KEY;
async function getCostaRicaWorkedDays(periodStart, periodEnd) {
const res = await fetch(
`${API}/CR/business-days/between?from=${periodStart}&to=${periodEnd}`,
{ headers: { Authorization: `Bearer ${KEY}` } }
);
const { data } = await res.json();
return data.business_days;
}
// April 1–30 2026: excludes Viernes Santo (Apr 3) + Juan Santamaría (Apr 11)
const workedDays = await getCostaRicaWorkedDays("2026-04-01", "2026-04-30");
// → 20 (not 22 as a naive calculator would say)Common use cases for Costa Rica
The same API key works for all 11 LATAM countries — Costa Rica is just the country code.
Costa Rican banks close on Juan Santamaría (Apr 11) and Guanacaste (Jul 25). Most international platforms don't model these holidays — payments queue unexpectedly.
is-business-day Free Semana Santa plus Juan Santamaría within the same week means April deliveries can slip by 3+ days. The official closure window is longer than the one official holiday.
business-days/add Starter Payroll in Costa Rica must account for two separate April non-working days plus the Guanacaste holiday in July. Generic LATAM libraries miss both.
business-days/between Starter Costa Rican legal deadlines run in business days. An SLA spanning early April without modeling Juan Santamaría will deliver 1 day late.
business-days/between Starter High-risk months for Costa Rica in 2026
These are the months where date calculation bugs are most likely to surface in production.
Viernes Santo (Apr 3, Fri) + Día de Juan Santamaría (Apr 11, Sat, observed Apr 10 Fri) — two non-working days within 8 calendar days.
Guanacaste Annexation (Jul 25, Sat in 2026). Observed Fri Jul 24 — easy to miss for systems assuming July has no LATAM-specific holidays.
Día de la Independencia (Sep 15, Tue in 2026). National celebration starts Sep 14 evening with torch relay — many businesses close early on the 14th.
Navidad (Dec 25, Fri) + year-end. Back-to-back with the weekend creates a 3-day window affecting 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 Costa Rica with commercial use.
Starter plan from $9/mo for full operational logic.