Code Examples
Practical examples for common use cases with the Festivo API, showcasing city-level precision and ISO-coded subdivisions.
Get City-Level Holidays
Fetch holidays for a specific city, including local observances like patron saint days (Pro plan):
Get City-Level Holidays Function
1import { FestivoClient } from '@festivo-io/festivo-sdk'23const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })45// Get holidays for Milan including Feast of Saint Ambrose6const { holidays } = await client.getCityHolidays('IT', 'IT-MILAN', 2026)7console.log('Found ' + holidays.length + ' holidays for Milan')89// Filter city-specific holidays10const citySpecific = holidays.filter(h =>11h.regions?.some(r => r.type === 'city')12)13console.log('City-specific: ' + citySpecific.length)14
Get All Holidays
Fetch national holidays for a country in a given year:
Get All Holidays Function
1import { FestivoClient } from '@festivo-io/festivo-sdk'23const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })45const { holidays } = await client.getHolidays('US', 2026)6console.log('Found ' + holidays.length + ' holidays')7
Filter by ISO-Coded Subdivisions
Query holidays for specific regions using standard ISO 3166-2 subdivision codes (Builder plan):
Get Regional Holidays with ISO Codes
1import { FestivoClient } from '@festivo-io/festivo-sdk'23const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })45// Usage: Get Scotland-specific holidays using ISO code GB-SCT6const { holidays } = await client.getRegionalHolidays("GB", "GB-SCT", 2026)7console.log("Found " + holidays.length + " holidays for Scotland")89// Check if holiday applies to specific region10const hasRegion = holidays[0].regions.some(r => r.code === 'GB-SCT')