API de Festivos Colombia - Documentación

1. Introducción

La API de Festivos de Colombia permite consultar información sobre los días festivos oficiales de Colombia de manera programática. Con esta API es posible:

• Obtener la lista completa de festivos para cualquier año, o para un rango de fechas.
• Verificar si una fecha específica es festivo.
• Consultar cuál es el próximo día festivo o una lista de próximos festivos.

Todas las respuestas están en formato JSON e incluyen los nombres de los festivos en español e inglés. Todas las fechas se muestran de acuerdo la zona horaria oficial de Colombia (GMT-5 / UTC-5).

2. Autenticación

La API admite dos métodos de autenticación:

Bearer Token (recomendado)

Incluir la API Key en el encabezado Authorization:

curl -X GET "https://festivos.com.co/api/v1/festivos" \
  -H "Authorization: Bearer TU_API_KEY"

Parámetro de consulta

Alternativamente, pasar la API Key como parámetro api_key:

curl -X GET "https://festivos.com.co/api/v1/festivos?api_key=TU_API_KEY"

Se recomienda usar Bearer Token ya que las URLs pueden quedar registradas en logs del servidor, historial del navegador y otros sistemas intermedios.

Para obtener una API Key es necesario crear una cuenta en el Panel de Desarrolladores. Cada cuenta puede tener hasta 3 API Keys activas.

Importante: La API Key debe mantenerse segura y no compartirse públicamente. Si una clave ha sido comprometida, es posible eliminarla y crear una nueva desde el Panel.

3. Límites de uso

Para garantizar un servicio estable, la API tiene los siguientes límites:

• Solicitudes por minuto: 20 por API Key
• Solicitudes por día: 1000 por API Key
• API Keys por cuenta: 3
• Rango de años válido: 1984 - 9999

Cuando se excede el límite de solicitudes, la respuesta incluye el código de estado 429 Too Many Requests.

El uso de la API debe ser razonable. Las cuentas o API Keys con actividad sospechosa o abusiva serán suspendidas.

4. Endpoints

4.1. Listar festivos

Obtiene la lista de todos los días festivos para un año específico. Opcionalmente permite filtrar por mes.

Parámetros de consulta

Ejemplo de solicitud

curl -X GET "https://festivos.com.co/api/v1/festivos?year=2025" \
  -H "Authorization: Bearer TU_API_KEY"

Ejemplo de respuesta

{
  "data": [
    {
      "date": "2026-01-01",
      "day_of_week_es": "Jueves",
      "day_of_week_en": "Thursday",
      "day_of_week_iso": 4,
      "name_es": "Año Nuevo",
      "name_en": "New Year's day"
    },
    {
      "date": "2026-01-12",
      "day_of_week_es": "Lunes",
      "day_of_week_en": "Monday",
      "day_of_week_iso": 1,
      "name_es": "Epifanía",
      "name_en": "Epiphany"
    },
    ...
  ]
}

4.2. Verificar fecha

Verifica si una fecha específica es un día festivo en Colombia.

Parámetros de consulta

Ejemplo de solicitud

curl -X GET "https://festivos.com.co/api/v1/festivos/check?date=2026-01-01" \
  -H "Authorization: Bearer TU_API_KEY"

Ejemplo de respuesta (es festivo)

{
  "festivo": true,
  "data": {
    "date": "2026-01-01",
    "day_of_week_es": "Jueves",
    "day_of_week_en": "Thursday",
    "day_of_week_iso": 4,
    "name_es": "Año Nuevo",
    "name_en": "New Year's day"
  }
}

Ejemplo de respuesta (no es festivo)

{
  "festivo": false,
  "data": null
}

4.3. Hoy

Verifica si hoy es un día festivo en Colombia.

Parámetros

No requiere.

Ejemplo de solicitud

curl -X GET "https://festivos.com.co/api/v1/festivos/today" \
  -H "Authorization: Bearer TU_API_KEY"

Ejemplo de respuesta (hoy es festivo)

{
  "festivo": true,
  "data": {
    "date": "2025-01-01",
    "day_of_week_es": "Miércoles",
    "day_of_week_en": "Wednesday",
    "day_of_week_iso": 3,
    "name_es": "Año Nuevo",
    "name_en": "New Year's Day"
  }
}

Ejemplo de respuesta (hoy no es festivo)

{
  "festivo": false,
  "data": null
}

4.4. Siguiente festivo

Obtiene información sobre el siguiente día festivo a partir de la fecha actual.

Nota: Si hoy es un día festivo, este endpoint devuelve el siguiente festivo, no hoy.

Parámetros

No requiere.

Ejemplo de solicitud

curl -X GET "https://festivos.com.co/api/v1/festivos/next" \
  -H "Authorization: Bearer TU_API_KEY"

Ejemplo de respuesta

{
  "data": {
    "date": "2026-01-12",
    "day_of_week_es": "Lunes",
    "day_of_week_en": "Monday",
    "day_of_week_iso": 1,
    "name_es": "Epifanía",
    "name_en": "Epiphany"
  }
}

4.5. Próximos festivos

Devuelve una lista de los próximos días festivos. Por defecto, devuelve los próximos 3 festivos (excluyendo hoy incluso si hoy es festivo).

Parámetros de consulta

Ejemplo de solicitud

curl -X GET "https://festivos.com.co/api/v1/festivos/upcoming?limit=5" \
  -H "Authorization: Bearer TU_API_KEY"

Ejemplo de respuesta

{
  "data": [
    {
      "date": "2026-01-12",
      "day_of_week_es": "Lunes",
      "day_of_week_en": "Monday",
      "day_of_week_iso": 1,
      "name_es": "Epifanía",
      "name_en": "Epiphany"
    },
    {
      "date": "2026-03-23",
      "day_of_week_es": "Lunes",
      "day_of_week_en": "Monday",
      "day_of_week_iso": 1,
      "name_es": "Día de San José",
      "name_en": "Saint Joseph's Day"
    },
    {
      "date": "2026-04-02",
      "day_of_week_es": "Jueves",
      "day_of_week_en": "Thursday",
      "day_of_week_iso": 4,
      "name_es": "Jueves Santo",
      "name_en": "Maundy Thursday"
    },
    ...
  ]
}

4.6. Festivos por rango de fechas

Devuelve todos los días festivos dentro de un rango de fechas especificado. El rango máximo es de 1 año.

Parámetros de consulta

Ejemplo de solicitud

curl -X GET "https://festivos.com.co/api/v1/festivos/range?from=2026-01-01&to=2026-01-31" \
  -H "Authorization: Bearer TU_API_KEY"

Ejemplo de respuesta

{
  "data": [
    {
      "date": "2026-01-01",
      "day_of_week_es": "Jueves",
      "day_of_week_en": "Thursday",
      "day_of_week_iso": 4,
      "name_es": "Año Nuevo",
      "name_en": "New Year's day"
    },
    {
      "date": "2026-01-12",
      "day_of_week_es": "Lunes",
      "day_of_week_en": "Monday",
      "day_of_week_iso": 1,
      "name_es": "Epifanía",
      "name_en": "Epiphany"
    }
  ]
}

5. Formato de respuesta

Todas las respuestas siguen un formato consistente.

Campos de un festivo

6. Errores

La API utiliza códigos de estado HTTP estándar para indicar el resultado de las solicitudes.

Códigos de estado

Formato de error

Cuando ocurre un error, la respuesta incluye un mensaje descriptivo:

{
  "message": "Unauthenticated."
}

Para errores de validación (422), se incluyen detalles de los campos con errores:

{
  "message": "The year field must be at least 1984.",
  "errors": {
    "year": [
      "The year field must be at least 1984."
    ]
  }
}