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.

How to read empty vs non-empty regions

When you filter with regions=GB-SCT, the API returns holidays that either list GB-SCT or have empty subdivisions (nationwide). Regional-only holidays for other nations (e.g. England-only) are excluded.

Holiday type for subdivision-scoped rows is typically regional (and public: false when the holiday is not nationwide).

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

City-Level Holidays

Festivo holiday calendars have three geographic levels:

Festivo supports national, regional and city-level holiday calendars where city-level geographic data is available from its underlying sources. City coverage is discovered from that data rather than from a fixed list, so it varies by country — see the example below for Spain.

Festivo city identifiers

There is no ISO standard for cities, so city codes are Festivo identifiers, not ISO codes. They are formed from the country code and the city name, upper-cased, without accents, spaces or punctuation: ES-MADRID, ES-BARCELONA, BR-SAOPAULO. A city's regions entry names its ISO 3166-2 parent when the source establishes it:

1{
2  "code": "ES-MADRID",
3  "type": "city",
4  "parentRegion": "ES-MD"
5}

A city holiday is never reported as regional or nationwide, and a regional holiday is never reported as a city holiday. The legacy subdivisions string array is unchanged and contains the same codes.

Querying a city calendar

Pass the city identifier in regions. A city calendar contains the country's national holidays, the parent region's holidays and the city's own holidays — each holiday once. A region query never includes city-only holidays.

1{
2  "name": "Feast of St. Isidro",
3  "date": "2026-05-15",
4  "observed": "2026-05-15",
5  "substitute": false,
6  "type": "regional",
7  "public": false,
8  "country": "ES",
9  "subdivisions": [
10    "ES-MADRID"
11  ],
12  "regions": [
13    {
14      "code": "ES-MADRID",
15      "type": "city",
16      "parentRegion": "ES-MD"
17    }
18  ]
19}

City-level access

City holidays are part of plans with city-level access (city_holidays). Without it, city-only holidays are omitted from every response — they are never shown as regional or nationwide — and a city query returns the national and parent-region calendar.

Data quality

When a source restricts a holiday to a place Festivo cannot yet identify reliably, the holiday is withheld rather than published with a broader scope. Festivo never widens a city or regional holiday to a country-wide one.