Holidays API

API Documentation

v1

1. Introduction

The Colombia Public Holidays API provides programmatic access to information about Colombia's official public holidays. The API enables:

  • Retrieving the complete list of holidays for any year, or for a date range.
  • Checking if a specific date is a holiday.
  • Querying the next holiday or a list of upcoming holidays.

All responses are in JSON format and include holiday names in both Spanish and English. All dates are shown according to Colombia's official time zone (GMT-5 / UTC-5).

2. Authentication

The API supports two authentication methods:

Bearer Token (recommended)

Include the API Key in the Authorization header:

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

Query parameter

Alternatively, pass the API Key as an api_key parameter:

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

Bearer Token is recommended because URLs can be recorded in server logs, browser history, and other intermediate systems.

To obtain an API Key, create an account in the Developer Panel. Each account can have up to 3 active API Keys.

Important: Keep API Keys secure and never share them publicly. If a key has been compromised, delete it and create a new one from the Panel.

3. Rate limits

To ensure stable service, the API enforces the following limits:

  • Requests per minute: 20 per API Key
  • Requests per day: 1000 per API Key
  • API Keys per account: 3
  • Valid year range: 1984 - 9999

When the request limit is exceeded, the response includes status code 429 Too Many Requests.

API usage must be reasonable. Accounts or API Keys with suspicious or abusive activity will be suspended.

4. Endpoints

4.1. List holidays

GET /festivos

Returns all public holidays for a specific year. Optionally filter by month.

Query parameters

Parameter Tipo Descripción
year integer opcional Year to query (1984-9999). Default: current year
month integer opcional Month to filter (1-12)

Example request

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

Example response

{
  "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. Check date

GET /festivos/check

Checks if a specific date is a public holiday in Colombia.

Query parameters

Parameter Tipo Descripción
date string requerido Date in ISO 8601 format (YYYY-MM-DD)

Example request

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

Example response (is a holiday)

{
  "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"
  }
}

Example response (not a holiday)

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

4.3. Today

GET /festivos/today

Checks if today is a public holiday in Colombia.

Parameters

None.

Example request

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

Example response (today is a holiday)

{
  "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"
  }
}

Example response (today is not a holiday)

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

4.4. Next holiday

GET /festivos/next

Returns information about the next public holiday from the current date.

Note: If today is a public holiday, this endpoint returns the following holiday, not today.

Parameters

None.

Example request

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

Example response

{
  "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. Upcoming holidays

GET /festivos/upcoming

Returns a list of upcoming public holidays. By default, returns the next 3 holidays (excluding today even if today is a holiday).

Query parameters

Parameter Tipo Descripción
limit integer opcional Number of holidays to return (1-10). Default: 3
include_today boolean opcional Include today if it is a holiday. Default: false

Example request

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

Example response

{
  "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. Holidays by date range

GET /festivos/range

Returns all public holidays within a specified date range. The maximum range is 1 year.

Query parameters

Parameter Tipo Descripción
from string requerido Start date in ISO 8601 format (YYYY-MM-DD)
to string requerido End date in ISO 8601 format (YYYY-MM-DD). Maximum range: 1 year

Example request

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

Example response

{
  "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. Response format

All responses follow a consistent format.

Holiday fields

Field Tipo Descripción
date string Date in ISO 8601 format (YYYY-MM-DD)
day_of_week_es string Day of the week in Spanish (Lunes, Martes, etc.)
day_of_week_en string Day of the week in English (Monday, Tuesday, etc.)
day_of_week_iso integer Day of the week per ISO 8601 (1=Monday, 7=Sunday)
name_es string Official holiday name in Spanish
name_en string Official holiday name in English

6. Errors

The API uses standard HTTP status codes to indicate request results.

Status codes

Code Description
200 OK Request successful
400 Bad Request Invalid parameters
401 Unauthorized Missing or invalid API Key
422 Unprocessable Entity Validation error in parameters
429 Too Many Requests Request limit exceeded
500 Internal Server Error Server error

Error format

When an error occurs, the response includes a descriptive message:

{
  "message": "Unauthenticated."
}

For validation errors (422), details about the invalid fields are included:

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