API JSON pública del Calendario Laboral — EE. UU. (v1)

Q: ¿Qué formato devuelve la API?

Todas las respuestas son JSON con Content-Type application/json. Cada respuesta incluye un campo calendarType (labor o fiscal) y un disclaimer indicando que los datos son informativos.

Q: ¿Puedo filtrar por estado o condado?

Sí. La API ofrece endpoints específicos por estado (/us/v1/{año}/estados/{estado}.json) y por condado (/us/v1/{año}/estados/{estado}/{condado}.json). El resultado incluye festivos federales más los estatales o locales aplicables.

Esta API expone los calendarios laborales de Estados Unidos en formato JSON, incluyendo los 11 festivos federales establecidos en el Título 5 U.S.C. § 6103, festivos por estado y condado, y el calendario fiscal del IRS. Todas las rutas empiezan por /us/v1/{año}/... y devuelven JSON estático, ideal para integraciones en sistemas de payroll, RRHH, planificación de proyectos y automatización fiscal.

Años disponibles: 2025, 2026, 2027. Listado completo: 2025, 2026, 2027.

Web 2025 Web 2026 Web 2027

Los datos provienen de fuentes públicas del gobierno federal de EE. UU. (OPM, IRS). Este servicio es informativo y no constituye asesoramiento legal o fiscal.

Endpoints disponibles

/us/v1/{año}/nacionales.json — Festivos federales
/us/v1/{año}/estados.json — Estados (listado)
/us/v1/{año}/estados/{estado}.json — Festivos de un estado
/us/v1/{año}/estados/{estado}/{municipio}.json — Festivos de un condado
/us/v1/{año}/fiscal.json — Calendario fiscal IRS completo
/us/v1/{año}/fiscal/{perfil}.json — Fiscal por perfil (individuals, businesses, self-employed)

Todas las respuestas incluyen calendarType para identificar si el calendario es laboral o fiscal, y un campo disclaimer indicando que esta API no sustituye a fuentes oficiales.

El uso de la API exige atribución con enlace visible y no permite abuso de sincronizaciones.

Ejemplo de respuesta JSON

Respuesta del endpoint /us/v1/2026/nacionales.json (festivos federales):

{
  "year": 2026,
  "calendarType": "labor",
  "country": "US",
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "scope": "national",
      "type": "public_holiday"
    },
    {
      "date": "2026-07-04",
      "name": "Independence Day",
      "scope": "national",
      "type": "public_holiday"
    }
  ],
  "totalHolidays": 11,
  "disclaimer": "Datos informativos..."
}

La respuesta real incluye los 11 festivos federales completos con sus fechas observadas.

Campos de la respuesta

Campo	Tipo	Descripción
`year`	number	Año del calendario
`calendarType`	string	`"labor"` o `"fiscal"`
`country`	string	Código de país (`"US"`)
`holidays`	array	Lista de festivos con `date`, `name`, `scope` y `type`
`holidays[].date`	string	Fecha en formato ISO 8601 (`YYYY-MM-DD`)
`holidays[].name`	string	Nombre oficial del festivo
`holidays[].scope`	string	Ámbito: `"national"`, `"state"` o `"local"`
`holidays[].type`	string	Tipo de festivo (`"public_holiday"`)
`totalHolidays`	number	Número total de festivos en la respuesta
`disclaimer`	string	Aviso legal sobre el carácter informativo de los datos

Casos de uso

Payroll y RRHH: calcula business days para nóminas, periodos de vacaciones y onboarding de empleados.
Plazos fiscales (IRS): determina vencimientos de filing y pagos estimados excluyendo festivos federales.
Gestión de proyectos: planifica sprints y entregas descontando festivos del calendario laboral.
Automatización: integra los festivos en dashboards, ERPs, CRMs y herramientas de scheduling.
Apps de calendario: sincroniza festivos federales y estatales en aplicaciones móviles o web.

Ejemplos para 2026

/us/v1/2026/nacionales.json
/us/v1/2026/estados.json
/us/v1/2026/estados/alabama.json
/us/v1/2026/estados/alabama/montgomery.json
/us/v1/2026/fiscal.json
/us/v1/2026/fiscal/individuals.json

Uso web equivalente: festivos 2026 | calculadora de días laborables 2026.

Preguntas frecuentes

¿Qué datos incluye la API de festivos de EE. UU.?

La API incluye los 11 festivos federales establecidos en 5 U.S.C. § 6103, con sus fechas observadas, festivos por estado y condado, y el calendario fiscal del IRS. Cada festivo incluye nombre, fecha, ámbito y tipo.

¿La API es gratuita?

Sí, la API es pública y gratuita. Se requiere atribución con enlace visible al sitio. No se permite abuso de sincronizaciones (máximo una petición por segundo).

¿Qué formato devuelve la API?

Todas las respuestas son JSON con Content-Type application/json. Cada respuesta incluye un campo calendarType ("labor" o "fiscal") y un disclaimer indicando que los datos son informativos y no sustituyen a fuentes oficiales.

¿Puedo filtrar por estado o condado?

Sí. La API ofrece endpoints específicos por estado (/us/v1/{año}/estados/{estado}.json) y por condado (/us/v1/{año}/estados/{estado}/{condado}.json). El resultado incluye festivos federales más los estatales o locales aplicables.

¿Los datos incluyen las fechas observadas?

Sí. Cuando un festivo federal cae en sábado se registra la fecha observada del viernes anterior, y cuando cae en domingo se registra el lunes siguiente, siguiendo la normativa de la OPM. La API ya refleja las fechas observadas en el campo date.