HolidayAware API

Integrate holiday data into your applications

API Overview

The HolidayAware API provides programmatic access to our comprehensive holiday database. Use our API to retrieve holiday information for different countries, filter by religion or type, and integrate this data into your applications.

Base URL: https://api.holidayaware.com/v1

All API requests require authentication using an API key. You can obtain an API key by registering for an account.

Endpoints

Get Holidays

GET /holidays

Query Parameters

ParameterTypeRequiredDescription
countrystringYesCountry code (ISO 3166-1 alpha-2)
datestringNoDate in YYYY-MM-DD format (defaults to today)
upcomingnumberNoNumber of days to include for upcoming holidays (default: 7)
religionsstringNoComma-separated list of religion IDs to filter by
typesstringNoComma-separated list of holiday type IDs to filter by

Example Response

{
  "todayHolidays": [
    {
      "id": "1",
      "name": "Independence Day",
      "description": "Independence Day is a federal holiday in the United States...",
      "date": "2025-07-04",
      "country": "US",
      "type": "public",
      "religion": "secular"
    }
  ],
  "upcomingHolidays": [
    {
      "id": "2",
      "name": "Labor Day",
      "description": "Labor Day is a federal holiday in the United States...",
      "date": "2025-09-01",
      "country": "US",
      "type": "public",
      "religion": "secular"
    },
    // Additional holidays...
  ]
}

Export Calendar

POST /export-calendar

This endpoint generates an ICS file containing the specified holidays that can be imported into calendar applications.

Request Body

{
  "holidays": [
    {
      "id": "1",
      "name": "Independence Day",
      "description": "Independence Day is a federal holiday...",
      "date": "2025-07-04",
      "country": "US",
      "type": "public",
      "religion": "secular"
    },
    // Additional holidays...
  ]
}

The response will be an ICS file with the Content-Type header set to text/calendar.

Rate Limits

API requests are subject to the following rate limits:

  • Free tier: 100 requests per day
  • Basic tier: 1,000 requests per day
  • Premium tier: 10,000 requests per day
  • Enterprise tier: Custom limits

For more information about our API or to upgrade your plan, please contact us.