Skip to main content

​
Endpoint

POST https://api.bunny.build/api/v1/public-holidays

​
Authentication

HeaderRequiredValue
X-API-KeyYesYour API key (bun_...)
Content-TypeYesapplication/json

​
Overview

Retrieve a complete list of public holidays for any supported country, optionally filtered to a specific year. Returns holiday names in both English and the local language alongside ISO dates, enabling date-aware scheduling, SLA calculations, and calendar integrations.

​
Use cases

  • Skip holidays in business day calculations
  • Display regional holidays in scheduling or calendar UIs
  • Automate SLA deadline adjustments around public holidays
  • Build country-aware payroll or time-tracking systems

​
Details

Covers 100+ countries. Holiday data includes national and regional observances. The year field defaults to the current year when omitted. Country codes follow ISO 3166-1 alpha-2 (e.g. BR, US, DE).

​
Request body

FieldTypeRequiredDescription
countrystringYesISO 3166-1 alpha-2 country code (e.g. BR, US)
yearnumberNoYear to retrieve holidays for (default: current year, range: 1900–2100)

​
Example

{
  "country": "BR",
  "year": 2025
}

​
Response

​
200 OK

FieldTypeDescription
countrystringISO country code (uppercased)
yearnumberYear of the holidays
countintegerTotal number of holidays returned
holidaysobject[]Array of holiday objects
Each holiday object:
FieldTypeDescription
datestringISO 8601 date (YYYY-MM-DD)
localNamestringHoliday name in the local language
namestringHoliday name in English
countryCodestringISO country code
fixedbooleanWhether this holiday falls on the same date every year
globalbooleantrue if the holiday applies to the whole country, false if regional
countiesstring[] | nullList of county/region codes the holiday applies to (null if global)
launchYearinteger | nullYear the holiday was first observed (if known)
typesstring[]Holiday type tags, e.g. ["Public"]
Example 
{
  "country": "BR",
  "year": 2025,
  "count": 12,
  "holidays": [
    {
      "date": "2025-01-01",
      "localName": "Confraternização Universal",
      "name": "New Year's Day",
      "countryCode": "BR",
      "fixed": true,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": ["Public"]
    },
    {
      "date": "2025-04-21",
      "localName": "Tiradentes",
      "name": "Tiradentes' Day",
      "countryCode": "BR",
      "fixed": true,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": ["Public"]
    }
  ]
}

​
401 Unauthorized

{
  "detail": "Missing API key. Include X-API-Key header."
}

​
402 Payment Required

{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}

​
422 Unprocessable Entity

{
  "detail": "Unknown country code"
}

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

​
cURL example

curl -X POST https://api.bunny.build/api/v1/public-holidays \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"country": "BR", "year": 2025}'