Public Holidays API
Festivo's Public Holidays API is a fast, lightweight, modern, and RESTful JSON API providing city-level precision for public holidays, local holidays, religious holidays, and observances from 250+ countries, 5,500+ regions, and 1,000+ cities worldwide.
Key Features
- 🏙️ City-Level Accuracy - Query holidays by city for granular data (e.g., Milan's Feast of Saint Ambrose)
- 🌍 ISO-Coded Subdivisions - Standard ISO 3166-2 codes for precise regional filtering
- 🕐 Timezone-Aware - Accurate local observance times with timezone conversion
- 💻 Developer-First - Clear docs, SDKs, powerful filters, and ready-to-use code examples
- 🌐 Global Coverage - 250+ countries, 5,500+ regions, 1,000+ cities
- 🗣️ Multilingual - Holiday names in 190+ languages
Getting Started
REST
The Public Holidays API, like all modern APIs, is organized around REST principles. It uses predictable, resource-oriented URLs and standard HTTP status codes to indicate errors.
HTTPS
The Public Holidays API requires all communications to be secured with TLS 1.2 or greater.
API Versions
The Festivo API is currently on Version 3. All endpoints are prefixed with /v3/.
Note: V2 API was retired on March 15, 2026. Please use V3 for all integrations.
Your API Key
Your API key is your unique authentication key to access Festivo's Public Holidays API. To authenticate your requests, include your API key in the request using one of these methods:
- Recommended:
X-API-Keyheader - Alternative:
api_keyquery parameter (deprecated, use for legacy compatibility only)
Base URL
https://api.getfestivo.com/v3/
Quick Example
Getting city-level holidays for Milan, Italy in 2026 (including the Feast of Saint Ambrose):
https://api.getfestivo.com/v3/public-holidays/listRequest
1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?country=IT®ions=IT-MILAN&year=2026&api_key=YOUR_API_KEY" \2-H "X-API-Key: YOUR_API_KEY"
Response
1{2 "holidays": [3 {4 "date": "2026-01-01",5 "name": "New Year's Day",6 "type": "public",7 "observed": "2026-01-01",8 "public": true,9 "country": "SG",10 "subdivisions": []11 },12 {13 "date": "2026-01-26",14 "name": "Chinese New Year",15 "type": "public",16 "observed": "2026-01-26",17 "public": true,18 "country": "SG",19 "subdivisions": []20 }21 ],22 "total": 1123}
Why Festivo?
🌍 Global Coverage
We cover 250+ countries and 5,500+ regions worldwide, with continuous updates and additions.
🗣️ Multilingual Support
Holiday names available in 50+ languages to serve your global audience.
🏙️ City-Level Precision
Get city-specific holidays, not just country-wide data. Perfect for local applications.
🕐 Historical & Future Data
Access historical holiday data and future projections for planning and analytics.
🇪🇺 Business-Friendly
GDPR-compliant, EU-based, with proper invoicing, purchase order support, and SEPA Direct Debit.
⚡ Fast & Reliable
Low latency and high availability, with an uptime SLA on every paid plan: Builder 99.5%, Growth 99.6%, Pro 99.8%, Titan 99.95%. A 99.99% SLA is available to Titan / Enterprise customers as a contractual commitment — see pricing.
Features
- REST API - Simple, predictable HTTP endpoints
- Substitute Holidays - Automatic handling of holidays falling on weekends
- Multiple Holiday Types - Public, bank, observance, religious, and more
- Subdivision Filtering - Filter by state, province, or region
- Timezone Support - Get dates adjusted for specific timezones
- Bulk Operations - Fetch multiple years or countries in one request
- Webhooks - Get notified when holidays change (Growth and above)
Quick Links
- Quick Start Guide
- API Reference
- Code Examples
- Portal: Calendars & website widgets — publish versions, scoped tokens, quotas
- Portal: SSO (OIDC) for teams — workspace sign-in (Titan / enterprise)
- Pricing Plans
Need Help?
- Help center (docs, billing shortcuts, status): app.getfestivo.com/help
- Email: hello@getfestivo.com