Festivo Product Release — Faster API, Smarter Holiday Data & Platform Improvements
We’re excited to introduce our latest Festivo product release.
This update focuses on three core areas: data accuracy, API performance, and platform improvements — all designed to help you deliver reliable, location-aware holiday data with greater speed and clarity.
⚠️ Breaking Changes & Important Notices
V2 API Deprecation & Retirement
Action Required: The legacy V2 API endpoints will be retired and disabled on March 15, 2026.
If you're still using V2 endpoints (e.g., /v2/holidays, /v2/countries), you must migrate to V3 before this date to avoid service interruption.
What this means:
- All V2 API requests will return
410 Goneerrors after March 15, 2026 - V3 API offers improved performance, better data accuracy, and enhanced features
- Migration is straightforward — see our migration guide for details
Need help? Contact us at contact@getfestivo.com and we'll assist with your migration.
SDK Updates
We've released brand new official SDKs with improved type safety, better error handling, and full V3 API support:
- New official SDKs are now available for Python, Node.js, PHP, and more
- Legacy SDKs (pre-2026 versions) are now deprecated and will not receive updates
- All new SDKs include TypeScript definitions, comprehensive documentation, and async/await support
Visit our SDK documentation to download the latest versions.
🚀 City-Level Holiday Support — Now Live
Why City-Level Holidays Matter
Many countries have holidays that only apply to certain cities or regions. This is especially true in Italy, where almost every city celebrates its own patron saint's day or local festival. For example, Milan observes the Feast of Saint Ambrose on December 7th, while Rome celebrates Saints Peter and Paul on June 29th. These holidays are not recognized nationally, but they have a significant impact on local business operations, school closures, and public services.
Missing a city holiday can mean failed deliveries, closed offices, or missed opportunities for local marketing campaigns. For HR and payroll, it's essential to account for these days to ensure compliance and employee satisfaction.
Enhanced Subdivision Detection
Festivo now supports city-specific holidays across more than 1,000 cities worldwide, with an improved system for detecting and classifying geographic subdivisions.
This means more precise differentiation between regions and cities, resulting in:
- More accurate local holiday detection
- Better support for city-specific holidays and festivals
- Improved filtering for location-based queries
These enhancements are especially impactful in countries where holidays vary by city — such as Italy and other regions with strong local traditions.
Structured Subdivision Metadata
We've introduced a richer data model for subdivisions. API responses now include:
- A new
regionsfield with structured metadata - Clear typing between
cityandregionsubdivisions - Consistent data normalization across all endpoints
The existing subdivisions field remains unchanged to ensure backward compatibility.
API Response Format Enhancements
We've enriched our API responses with new metadata fields to help you build more robust integrations:
dataVersion Field
Every response now includes a dataVersion field indicating the data schema version. This helps you:
- Track which version of our data model you're working with
- Safely handle future API evolutions
- Implement version-specific logic if needed
deprecated Field
Endpoints and features approaching end-of-life now include a deprecated field with:
- Clear deprecation notices
- Migration guidance
- Timeline for changes
This gives you advance notice and time to update your integrations without surprises.
Enhanced regions Field
The new regions field provides structured subdivision data as an array of objects:
{
"regions": [
{
"code": "IT-MILAN",
"type": "city"
},
{
"code": "IT-88",
"type": "region"
}
]
}
Each region object includes:
code: The subdivision identifier (e.g., "MI" for Milan)type: Either"city"or"region"for precise classification
This structured format makes it easier to:
- Filter holidays by geographic level
- Build location-based UI components
- Implement city-specific business logic
All new fields are optional and additive — your existing code continues to work without modification.
Simple Integration
Getting city-specific holidays is straightforward. Simply add a city parameter to your API request:
curl "https://api.getfestivo.com/v3/public-holidays/list?country=IT&city=Milan&year=2024"
The response includes both national and city-specific holidays, giving you complete visibility into all relevant dates for that location.
🎯 New /check Endpoint for Quick Holiday Validation
We've introduced a new /check endpoint designed for fast, lightweight holiday validation without retrieving full holiday lists.
Why Use /check?
The /check endpoint is perfect when you need to:
- Quickly validate if a specific date is a holiday
- Check working day status for business logic
- Implement real-time date validation in forms
- Build lightweight integrations that don't need full holiday data
Simple and Efficient
Instead of fetching entire holiday lists and filtering client-side, simply query a specific date:
curl "https://api.getfestivo.com/v3/public-holidays/check?country=IT&date=2024-12-25"
The response is compact and includes:
{
"isHoliday": true,
"isWorkingDay": false,
"name": "Christmas Day",
"date": "2024-12-25",
"subdivisions": ["IT"]
}
Key Benefits
- Faster responses — optimized for single-date queries
- Lower bandwidth — minimal payload size
- Better caching — date-specific cache keys for maximum efficiency
- City-aware — supports city and region parameters just like
/list
Perfect for high-frequency validation scenarios where performance matters.
For complete API documentation, visit our API reference.
⚡ Faster API Performance
Improved Response Times
We’ve significantly optimized database queries and aggregation pipelines:
- Cached requests typically return in under 100 ms
- Initial uncached requests are now noticeably faster
- Reduced payload size improves network efficiency
Smarter Caching Architecture
Our new caching strategy includes:
- Access-aware cache keys based on subscription entitlements
- Tiered caching for user data, subscription limits, and holiday datasets
- Defensive in-memory fallback if Redis is unavailable
These improvements ensure both performance and reliability at scale.
🔒 Subscription-Aware Holiday Filtering
API responses now dynamically adjust based on subscription entitlements:
- Users without city-level access automatically receive region-level holidays
- Filtering happens at the database layer for improved performance
- API contracts remain unchanged for existing clients
This makes responses clearer while maintaining consistent integration behavior.
🛠 Reliability & Platform Improvements
We’ve implemented several backend improvements to enhance system stability:
- Enhanced error monitoring and upgraded observability tooling
- Improved request tracing with detailed performance logging
- Stronger error handling and defensive validation
- Reduced code duplication and improved maintainability
These changes help us maintain high uptime and faster issue resolution.
🌐 Brand New Landing Page
We've completely rebuilt our website from the ground up with a modern, user-friendly design:
Modern Technology Stack
Our new landing page is built with Next.js 16, TypeScript, and Tailwind CSS v4, delivering:
- Lightning-fast performance with optimized static page generation
- Responsive design that looks great on any device
- Dark mode support for comfortable viewing in any lighting
- SEO optimized for better discoverability
Enhanced Content & Navigation
The redesigned site includes:
- Comprehensive documentation hub with interactive API reference and getting started guides
- Industry-specific use cases showcasing real-world applications for HR, e-commerce, financial services, and more
- Expanded FAQ section with 12+ detailed answers to common questions
- Blog and changelog keeping you informed about product updates and best practices
- Improved about and contact pages making it easier to learn about Festivo and get in touch
Better User Experience
- Clearer navigation with organized content structure
- Enhanced visual hierarchy and readability
- Customer testimonials and social proof
- Interactive examples and code snippets
- Streamlined contact and support options
The new site reflects our commitment to providing not just great API technology, but also a great experience for learning about and using our service.
💼 Pricing & Platform Experience Updates
Updated Plan Names
We’ve refreshed plan names to better reflect how customers use Festivo:
- Developer → Explorer
- Starter → Builder
- Startup → Growth
- Business → Pro
- Enterprise → Titan
Improved Pricing Experience
Our redesigned pricing page now includes:
- Clearer plan comparison and navigation
- Transparent annual savings visibility
- Smart currency detection based on your location
- Expanded FAQs for common pricing questions
Monthly and annual billing options remain available as before.
🔄 Backward Compatibility
No action is required for V3 API users.
- Existing V3 integrations continue to function normally
- API contracts remain unchanged
- Legacy subdivision formats are automatically normalized
- New fields are additive and optional
You can adopt new metadata features at your own pace.
V2 API users: Please see the Breaking Changes section at the top of this announcement for important migration information.
📈 What This Means for You
With this release, Festivo delivers:
- More accurate city-level holiday coverage
- Faster and more consistent API responses
- Improved reliability and monitoring
- A clearer and more user-friendly pricing experience
Our goal remains the same: helping you build applications powered by reliable, globally accurate holiday data.
🙌 Thank You
Thank you for building with Festivo.
We’re excited to keep improving the platform and supporting your projects worldwide.
For technical details, updated documentation, or support, please contact us at contact@getfestivo.com.