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