Subdivisions & City-Level Holidays

Festivo supports both ISO-standard subdivisions (states, provinces, regions) and city-level holidays, which are not covered by ISO 3166-2.

New: Structured Regions Field

As of the latest API update, holiday responses now include a structured regions field that provides detailed geographic classification:

1{
2  "name": "Feast of Saint Ambrose",
3  "date": "2026-12-07",
4  "country": "IT",
5  "subdivisions": [
6    "IT-MILAN"
7  ],
8  "regions": [
9    {
10      "code": "IT-MILAN",
11      "type": "city"
12    },
13    {
14      "code": "IT-88",
15      "type": "region"
16    }
17  ]
18}

The regions field is an array of objects, each containing:

• code: The subdivision or city identifier
• type: Either "city" or "region" for precise classification

This makes it easier to:

• Filter holidays by geographic level
• Build location-aware UI components
• Distinguish between city-specific and region-wide holidays
• Implement sophisticated business logic based on location

Note: The legacy subdivisions field (string array) remains available for backward compatibility.

ISO 3166-2 Subdivisions

Most countries use ISO 3166-2 codes to identify their administrative subdivisions. These codes are used in the API to filter holidays for specific regions.

Format: {COUNTRY}-{SUBDIVISION}

Common ISO 3166-2 Codes

Usage example with ISO codes:

1curl -X GET "https://api.getfestivo.com/v3/public-holidays/list?api_key=YOUR_API_KEY&country=GB&year=2026&regions=GB-SCT"

City-Level Holidays

Some countries, especially Italy, have holidays specific to cities or municipalities. These use Festivo's city codes in the same format as ISO subdivisions.

Format: {COUNTRY_CODE}-{CITY}

Supported Cities

Why City-Level Holidays Matter

City-level holidays are especially important in Italy, where many cities have their own patron saint days and local observances. These can affect:

• ✈️ Delivery schedules - Food, logistics, e-commerce operations
• 🏢 School and government office closures - Municipal services unavailable
• 💼 Local business operations - Shops, restaurants, services may be closed
• 👥 Workforce management - Employee availability and compliance

Real-world example: On December 7th (Feast of Saint Ambrose), Milan's city offices, many shops, and schools are closed, but Rome operates normally. Generic "Italy holidays" data would miss this critical local observance.

To query city-level holidays, use the regions parameter with the city code format {COUNTRY_CODE}-{CITY}:

1import { FestivoClient } from '@festivo-io/festivo-sdk'
2
3const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })
4const res = await client.request('/v3/public-holidays/list?country=IT&regions=IT-MILAN&year=2026')
5console.log(res.holidays)
6

You can also query multiple cities or mix cities with regions:

1import { FestivoClient } from '@festivo-io/festivo-sdk'
2
3const client = new FestivoClient({ apiKey: process.env.FESTIVO_API_KEY })
4const res = await client.request('/v3/public-holidays/list?country=IT&regions=IT-MILAN,IT-ROME&year=2026')
5console.log(res.holidays)
6

How to Get All Subdivisions

To get a list of all subdivisions for a country, use the API's premium filters or refer to the documentation for supported codes.

Why City-Level Holidays Matter

City-level holidays are especially important in Italy, where many cities have their own patron saint days and local observances. These can affect:

• Delivery schedules (food, logistics, e-commerce)
• School and government office closures
• Local business operations

Festivo provides comprehensive coverage for both ISO subdivisions and city-level holidays, ensuring your applications and business logic are accurate and up-to-date.

Working with the Regions Field

The structured regions field makes it easy to filter and classify holidays programmatically:

Filter by Type

1// Get only city-specific holidays
2const cityHolidays = holidays.filter(holiday =>
3holiday.regions.some(region => region.type === 'city')
4);
5
6// Get only region-wide holidays
7const regionalHolidays = holidays.filter(holiday =>
8holiday.regions.some(region => region.type === 'region')
9);

Check if Holiday Applies to a Location

1function isHolidayInLocation(
2holiday: Holiday,
3locationCode: string
4): boolean {
5return holiday.regions.some(
6  region => region.code === locationCode
7);
8}
9
10// Check if holiday applies to Milan
11if (isHolidayInLocation(holiday, 'IT-MILAN')) {
12console.log('Holiday observed in Milan');
13}

Build Location-Specific UI

1function HolidayCard({ holiday }) {
2const cityHolidays = holiday.regions.filter(r => r.type === 'city');
3const regionHolidays = holiday.regions.filter(r => r.type === 'region');
4
5return (
6  <div>
7    <h3>{holiday.name}</h3>
8    {cityHolidays.length > 0 && (
9      <div>
10        <strong>Cities:</strong> {cityHolidays.map(r => r.code).join(', ')}
11      </div>
12    )}
13    {regionHolidays.length > 0 && (
14      <div>
15        <strong>Regions:</strong> {regionHolidays.map(r => r.code).join(', ')}
16      </div>
17    )}
18  </div>
19);
20}

Need More Codes?

If you need a full list of supported subdivision or city codes, contact support@getfestivo.com or check the API documentation for updates.