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
Parameter | Type | Required | Description |
---|---|---|---|
country | string | Yes | Country code (ISO 3166-1 alpha-2) |
date | string | No | Date in YYYY-MM-DD format (defaults to today) |
upcoming | number | No | Number of days to include for upcoming holidays (default: 7) |
religions | string | No | Comma-separated list of religion IDs to filter by |
types | string | No | Comma-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.