Migrating from V2 to V3 API
V2 API Retirement Notice
The V2 API will be retired and disabled on March 15, 2026. All V2 endpoints will return
410 Gone
errors after this date. Please migrate to V3 before this deadline.
The V3 API represents a significant improvement over V2, with better performance, enhanced data quality, and new features like city-level holiday support. This guide will help you migrate your integration smoothly.
Why Migrate to V3?
The V3 API offers several advantages over V2:
- Better Performance: Optimized queries and improved caching (sub-100ms response times)
- City-Level Holidays: Support for 1000+ cities worldwide with granular location data
- Enhanced Data Model: Structured subdivision metadata and clearer response formats
- New Endpoints:
/checkendpoint for fast single-date validation - Improved Error Handling: More descriptive error messages and better status codes
- Future-Proof: All new features and improvements will be V3-only
Key Differences Between V2 and V3
Base URL Changes
V2:
https://api.getfestivo.com/v2/
V3:
https://api.getfestivo.com/v3/
Endpoint Changes
| V2 Endpoint | V3 Endpoint | Notes |
|---|---|---|
/v2/holidays | /v3/public-holidays/list | Renamed for clarity |
/v2/countries | /v3/countries | No change in path structure |
| N/A | /v3/public-holidays/check | New: Fast single-date validation |