FAQ & Best Practices
Common questions and best practices for using the Festivo API effectively.
Frequently Asked Questions
How do city-level holidays work?
City-level holidays are local observances specific to individual cities, such as patron saint days in Italy. These holidays are not recognized nationally but are official in specific cities.
Example: Milan celebrates the Feast of Saint Ambrose (Sant'Ambrogio) on December 7th. This is a public holiday in Milan but not in other Italian cities.
To query city-level holidays, use the regions parameter with city code format {COUNTRY_CODE}-{CITY} (Pro plan):
1import { FestivoClient } from '@festivo-io/festivo-sdk'23const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })4const res = await client.request('/v3/public-holidays/list?country=IT®ions=IT-MILAN&year=2026')5console.log(res.holidays)6
What are ISO 3166-2 subdivision codes?
ISO 3166-2 is the international standard for subdivision codes (states, provinces, regions). Festivo uses these codes for precise regional filtering.
Format: {COUNTRY}-{SUBDIVISION}
Examples:
GB-SCT- ScotlandUS-CA- CaliforniaDE-BY- BavariaFR-75- Paris
Use the regions parameter to filter by ISO codes (Builder plan and above).
How do I handle holidays in multiple timezones?
Use the timezone parameter to get holidays with accurate local times (Growth plan):
1import { FestivoClient } from '@festivo-io/festivo-sdk'23const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })4const { holidays } = await client.getHolidays('JP', 2026, { timezone: 'Asia/Tokyo' })5// Timestamps are in Tokyo local time6console.log(holidays[0].start)7console.log(holidays[0].end)8