feriados.io vs Holiday API

Feature comparison

Why LATAM accuracy matters more than you think

A holiday API that lists January 6th as "Reyes Magos" in Colombia is technically correct — that is the holiday. But January 6th is a regular business day in 2026. The holiday is observed on January 12th. If your payment processor checks January 6th and gets "holiday", it's wrong. If it checks January 12th and doesn't know it's a holiday, it's also wrong.

When to choose each

What you'd have to build yourself with Holiday API

Holiday API has no is-business-day endpoint. To check if a date is workable in Colombia you'd need to fetch the year's holidays, apply Ley Emiliani shift logic, then evaluate the date. feriados.io handles all of that in a single request.

// 1. Fetch all holidays for the year
const { response } = await holidayapi.holidays({
  country: "CO", year: 2026
});

// 2. Apply Ley Emiliani shift logic yourself
// (18 of 20 Colombian holidays move to Monday)
function applyEmiliani(holidays) {
  return holidays.map(h => {
    const d = new Date(h.date);
    if (EMILIANI_HOLIDAYS.includes(h.name)) {
      // find next Monday...
    }
    return h;
  });
}
const observed = applyEmiliani(response.holidays);

// 3. Check weekend + holiday lookup
const day = new Date(targetDate).getDay();
const isWeekend = day === 0 || day === 6;
const isHoliday = observed.some(h => h.date === targetDate);

// 4. Finally answer the question
const isBusinessDay = !isWeekend && !isHoliday;

// One API call — done
const res = await fetch(
  "https://api.feriados.io/v1/CO" +
  "/is-business-day?date=2026-01-12",
  { headers: { Authorization: `Bearer ${KEY}` } }
);

const { data } = await res.json();
// data.is_business_day → true
// data.holiday → null
//
// Jan 6 (Reyes Magos) is observed Jan 12
// per Ley Emiliani — already handled.

// Not available — Holiday API workday
// endpoint only goes forward.
// You'd need to implement a reverse loop:
let current = new Date(fromDate);
let counted = 0;
while (counted < daysToSubtract) {
  current.setDate(current.getDate() - 1);
  // check weekend + fetch holidays...
  if (isWorkday(current, holidays)) counted++;
}
// Result: many requests + custom logic

const res = await fetch(
  "https://api.feriados.io/v1/CO" +
  "/business-days/subtract" +
  "?fromDate=2026-03-10&days=5",
  { headers: { Authorization: `Bearer ${KEY}` } }
);
const { data } = await res.json();
// data.result_date → "2026-03-03"
// (Argentina/Colombia rules applied)

Migrating from Holiday API

The main changes are: move the API key from a query param to a header, move the country into the URL path, and update the response field name. Workday arithmetic endpoints have direct equivalents — plus several new ones not available in Holiday API.

// Before (Holiday API)
const { response } = await holidayapi.workday({
  country: "CO", start: "2026-01-07", days: 5
});
const resultDate = response.workday.date;

// After (feriados.io)
const res = await fetch(
  "https://api.feriados.io/v1/CO/business-days/add?fromDate=2026-01-07&days=5",
  { headers: { Authorization: `Bearer ${process.env.FERIADOS_API_KEY}` } }
);
const { data } = await res.json();
const resultDate = data.result_date;
// Also includes: data.from, data.business_days_added, data.country