Brazilian Administrative Codes Explained for Developers: IBGE, UF, and Municipal Holidays

When international engineering teams expand their software, SaaS, fintech, or AI agents into Brazil, they immediately encounter a set of unfamiliar administrative abbreviations and geographical concepts: UF, IBGE Codes, and a complex 3-tier holiday hierarchy. Understanding these concepts is essential to preventing database errors, billing miscalculations, and compliance failures.

In many countries, public holidays and administrative regions are straightforward: holidays are either nationwide or governed by a small number of states or provinces, and city names can be safely stored as simple text strings. In Brazil, attempting to hardcode holidays or look up cities by name alone will quickly break your application.

In this guide, we demystify Brazilian administrative geography for international developers, explain why the 7-digit IBGE municipality code is the most important primary key in Brazilian software architecture, and show how to handle federal, state, and local calendars cleanly via API.

1. What is a UF (Unidade da Federação)?

UF stands for Unidade da Federação (Federating Unit). Brazil is a federal republic composed of 26 states and 1 Federal District (Brasília — DF). In software databases and APIs, each state is universally represented by a standardized two-letter uppercase postal code.

Common examples include SP for São Paulo, RJ for Rio de Janeiro, MG for Minas Gerais, and AM for Amazonas.

Why UF matters for calendars: Unlike centralized countries, Brazilian state legislatures have constitutional authority to enact official state holidays (up to 3 per year). For example, July 9 is a statutory public holiday across the entire state of São Paulo (Constitutionalist Revolution), meaning government offices and local business operations close. However, July 9 is a regular working day in neighboring Rio de Janeiro or Minas Gerais! If your software only evaluates national holidays, your billing and scheduling engines will fail across state borders.

2. What is an IBGE Code and Why City Names Are Not Unique?

The IBGE (Instituto Brasileiro de Geografia e Estatística— Brazilian Institute of Geography and Statistics) is Brazil's official national statistical and geographical agency, equivalent to the U.S. Census Bureau, INSEE in France, or ONS in the UK.

Brazil is divided into exactly 5,570 municipalities (municípios). A common mistake foreign developers make is attempting to use city names as primary keys or database query parameters. In Brazil, this is mathematically impossible due to extreme naming ambiguity:

• ⚠️Identical City Names Across States: There are 23 different municipalitiesnamed "São Domingos", 21 named "Bom Jesus", and 18 named "Santa Terezinha" spread across various Brazilian states.
• ⚠️Spelling Variations and Diacritics: Portuguese city names frequently include accents, cedillas, and hyphens (e.g., São João d'Aliança or Embu-Guaçu). Text matching is highly prone to encoding errors and user typos.
• ⚠️Homonyms within the Same State: Even within a single state, city names can be nearly identical or confusingly similar, making string matching unreliable for financial or tax transactions.

The 7-Digit Standard Census Identifier

To eliminate ambiguity, all Brazilian governmental systems, tax invoices (NF-e), Central Bank financial networks (Pix, TED, Boleto), logistics providers, and modern APIs use the 7-digit IBGE code as the universal, immutable primary key for every municipality.

For example, the IBGE code for the city of São Paulo is 3550308. Let's break down its mathematical structure:

Whenever you store a Brazilian address, customer profile, or warehouse location in your database, always store the 7-digit IBGE code alongside the UF. This ensures sub-millisecond precision when querying localized data.

3. The 3-Tier Holiday Hierarchy: Federal, State, and Municipal

In the United States or Europe, public holidays are predominantly national, with occasional regional variations. In Brazil, public holidays operate on an independent 3-tier legislative hierarchy:

• 1.National Holidays (Feriados Nacionais):Enacted by federal law and mandatory across all 26 states and over 5,570 cities. Examples include New Year's Day (Jan 1), Tiradentes (Apr 21), Independence Day (Sep 7), and Christmas (Dec 25).
• 2.State Holidays (Feriados Estaduais): Enacted by state legislative assemblies. Each state can declare up to 3 official civil holidays. For example, July 2 is Independence Day in Bahia, and September 20 is the Farroupilha Revolution in Rio Grande do Sul.
• 3.Municipal Holidays (Feriados Municipais): Enacted by city councils. According to Federal Law No. 9,093/1995, each of the 5,570 municipalities can declare up to 4 religious or founding holidays per year. This includes the city founding anniversary (Aniversário da Cidade) and local patron saints (such as Saint George on April 23 in Rio de Janeiro City).

4. Other Essential Concepts: Facultativos and Bancários

To build robust software for Brazil, developers must also understand two specialized calendar classifications:

Pontos Facultativos (Optional Observances)

A ponto facultativo is an optional observance declared by administrative decrees. The most prominent examples are Carnival (Monday and Tuesday before Ash Wednesday) and Corpus Christi.

At the federal level, these dates are not statutory holidays; federal government agencies close, but private companies are legally free to open or grant a day off. However, here is the catch: hundreds of city councils across Brazil have enacted local municipal laws elevating Corpus Christi or Carnival into mandatory public holidays within their city limits!

Feriados Bancários (Banking Holidays & Settlement)

If your software processes payments, boletos, or interbank transfers, you must follow the rules of the National Monetary Council (CMN Resolution 4,880/2020) and the FEBRABAN banking calendar.

While bank branches close on municipal and state holidays within that specific jurisdiction, electronic interbank clearing (such as 24/7 Pix instant payments or centralized TED settlement) operates continuously nationwide unless it is a national banking holiday.

5. Automating Holiday Validation by IBGE Code

The cleanest way to handle Brazilian geography and calendar rules is to query a specialized REST API using the 7-digit IBGE code. Here is how simple it is in Python:

import requests

# Example: Checking if January 25 is a holiday in São Paulo City
# Using the official 7-digit IBGE census code: 3550308
ibge_code = "3550308"
check_date = "2026-01-25"

url = f"https://api.feriadosapi.com/v1/feriados/cidade/{ibge_code}?ano=2026"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
holidays = response.json()

for holiday in holidays:
    if holiday["data"] == check_date:
        print(f"🎉 Holiday Found: {holiday['nome']} ({holiday['tipo']})")
        # Output: 🎉 Holiday Found: Aniversário de São Paulo (MUNICIPAL)

The API returns a clean, structured JSON array containing all national, state, and municipal holidays for that specific city, automatically including the boolean bancario flag:

[
  {
    "data": "2026-01-01",
    "nome": "Confraternização Universal",
    "tipo": "NACIONAL",
    "bancario": true
  },
  {
    "data": "2026-01-25",
    "nome": "Aniversário de São Paulo",
    "tipo": "MUNICIPAL",
    "bancario": false,
    "codigo_ibge": "3550308"
  },
  {
    "data": "2026-07-09",
    "nome": "Revolução Constitucionalista",
    "tipo": "ESTADUAL",
    "bancario": false,
    "uf": "SP"
  }
]

Ready to make your software 100% compliant with Brazilian geographical and calendar rules? Get your free Feriados API token today and query all 5,570 municipalities with sub-millisecond latency.