Developer Documentation
Comprehensive holiday and celebration reference covering 50 holidays across 50 countries, 200 guides, 120 glossary terms, 40 cultural traditions, 25 holiday comparisons, 10 world religions, 8 seasonal pages, 30 notable weeks, 105 blog articles, and 15 interactive tools including holiday countdown, bridge-day calculator, and long weekend planner. Calendar dates, iCal feeds, and RSS available.
- 50 major holidays from around the world with dates, history, and customs
- 50 countries with public holiday schedules and annual calendars
- Holiday × Country pages (how each holiday is celebrated per country)
- Holiday × Year pages (dates for specific years)
- 200 educational guides on holiday traditions, cultural practices, and calendar systems
- 120 glossary terms for holiday and calendar terminology
- 40 cultural traditions from diverse regions and civilizations
- 25 holiday comparison pages (side-by-side analysis)
- 10 world religion profiles with associated holidays
- 8 seasonal pages (spring, summer, autumn, winter + equinox/solstice)
- 30 notable weeks (awareness weeks, cultural celebrations)
- 105 blog articles on holiday topics
- Calendar date pages with holidays, seasons, and notable events
- Long weekend planner by country and year
- Bridge-day calculator for maximizing vacation days
- iCal feeds per country and per holiday
- RSS/Atom feeds for upcoming holidays and blog
- 15 languages: en, ko, ja, zh-hans, es, fr, de, pt, ru, vi, tr, ar, hi, th, id
Quick Start
curl -s "https://holidayfyi.com/api/v1/today/"
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/holidays/ | List all holidays |
| GET | /api/v1/holidays/{slug}/ | Holiday detail |
| GET | /api/v1/countries/ | List all countries |
| GET | /api/v1/countries/{slug}/ | Country detail |
| GET | /api/v1/countries/{slug}/holidays/ | Country holidays list |
| GET | /api/v1/today/ | Holidays happening today |
| GET | /api/v1/upcoming/ | Upcoming holidays |
| GET | /api/v1/instances/ | Holiday instances (dated occurrences) |
| GET | /api/v1/calendar/ | Calendar data |
| GET | /api/v1/glossary/ | Glossary terms |
| GET | /api/v1/glossary/{slug}/ | Glossary term detail |
| GET | /api/v1/guides/ | Guides list |
| GET | /api/v1/guides/{slug}/ | Guide detail |
| GET | /api/v1/traditions/ | Traditions list |
| GET | /api/v1/traditions/{slug}/ | Tradition detail |
| GET | /api/v1/comparisons/ | Comparisons list |
| GET | /api/v1/tools/ | Tools list |
| GET | /api/v1/seasons/ | Seasons list |
| GET | /api/v1/weeks/ | Notable weeks list |
| GET | /api/v1/blog/ | Blog posts list |
| GET | /api/v1/faqs/ | FAQs list |
| GET | /api/v1/bridge-days/ | Bridge-day calculation |
| GET | /api/v1/search/ | Search holidays, countries, glossary |
| GET | /api/v1/stats/ | Site statistics |
URL Patterns
Use these patterns to construct URLs programmatically:
/
Homepage — today's holidays, upcoming celebrations (e.g. /)
/today/
Holidays happening today worldwide (e.g. /today/)
/holiday/{slug}/
Holiday detail with history, customs, dates (e.g. /holiday/christmas/)
/holiday/{slug}/{year}/
Holiday dates for a specific year (e.g. /holiday/christmas/2026/)
/holiday/{holiday}/{country}/
Holiday in a specific country (e.g. /holiday/christmas/germany/)
/country/
Browse all 50 countries (e.g. /country/)
/country/{slug}/
Country detail with public holidays (e.g. /country/united-states/)
/country/{slug}/{year}/
Country holidays for a specific year (e.g. /country/united-states/2026/)
/guide/
Browse all 200 guides (e.g. /guide/)
/guide/{slug}/
Guide article (e.g. /guide/history-of-easter/)
/glossary/
Holiday terminology glossary (120 terms) (e.g. /glossary/)
/glossary/{slug}/
Glossary term detail (e.g. /glossary/solstice/)
/tradition/
Browse 40 cultural traditions (e.g. /tradition/)
/tradition/{slug}/
Tradition detail (e.g. /tradition/hanami/)
/compare/
Browse 25 holiday comparisons (e.g. /compare/)
/compare/{slug}/
Holiday comparison detail (e.g. /compare/christmas-vs-hanukkah/)
/season/
Browse 8 seasons (e.g. /season/)
/season/{slug}/
Season detail with holidays (e.g. /season/spring/)
/week/
Browse 30 notable weeks (e.g. /week/)
/week/{slug}/
Notable week detail (e.g. /week/golden-week/)
/long-weekends/{country}/{year}/
Long weekends for a country in a year (e.g. /long-weekends/united-states/2026/)
/tool/
Browse 15 interactive tools (e.g. /tool/)
/tool/{slug}/
Tool page (e.g. /tool/holiday-countdown/)
/tool/bridge-day-calculator/{country}/
Bridge-day calculator for a country (e.g. /tool/bridge-day-calculator/germany/)
/tool/bridge-day-calculator/{country}/{year}/
Bridge days for a country and year (e.g. /tool/bridge-day-calculator/germany/2026/)
/calendar/
Calendar index (e.g. /calendar/)
/calendar/{year}/
Year calendar with holidays (e.g. /calendar/2026/)
/calendar/{year}/{month}/
Month calendar (e.g. /calendar/2026/january/)
/calendar/{year}/q{quarter}/
Quarter calendar (e.g. /calendar/2026/q1/)
/calendar/{year}/week/{week}/
Week calendar (e.g. /calendar/2026/week/1/)
/calendar/day/{slug}/
Calendar date detail (e.g. /calendar/day/2026-01-01/)
/blog/
Holiday articles and stories (105) (e.g. /blog/)
/blog/{slug}/
Blog article detail (e.g. /blog/history-of-new-year/)
/search/
Search holidays, countries, guides (e.g. /search/?q=easter)
Response Format
All endpoints return JSON with pagination:
Example JSON response
{
"count": 636,
"next": "https://example.com/api/v1/items/?page=2",
"previous": null,
"results": [
{"slug": "example", "name": "Example Item", "...": "..."}
]
}
OpenAPI Specification
Full API schema available as OpenAPI 3.1.0 JSON. Import into Swagger UI, Postman, or any OpenAPI-compatible tool.
SDK Packages
PyPI
pip install holidayfyi
Holiday dates, Easter calculation, 200+ countries (v0.1.2)
npm
npm install holidayfyi
TypeScript holiday utilities (v0.1.1)
Embed Widget
Embed data cards on your site:
https://widget.holidayfyi.com
npm install holidayfyi-embed
Format Support
- Markdown endpoints: Append
.mdto any page URL for LLM-friendly markdown output. - Internationalization: Content available in 14 languages: ko, ja, zh-hans, es, fr, de, pt, ru, vi, tr, ar, hi, th, id.