Skip to content

View or edit on GitHub

This page is synchronized from trase/data/brazil/spatial/boundaries/ibge/divisao_territorial/brazil_ibge_divisao_territorial.md. Last modified on 2026-11-02 10:41 CET by dependabot[bot]. Please view or edit the original file there; changes should be reflected here after a midnight build (CET time), or manually triggering it with a GitHub action (link).

{% docs brazil_ibge_divisao_territorial %}

Divisão Territorial Brasileira, 2020-2025

The Divisão Territorial Brasileira is the annual register of Brazil's territorial units, published by IBGE (Instituto Brasileiro de Geografia e Estatística). It lists every state, municipality, district and subdistrict with its code and name. It is a list, not a map: it has no boundaries or areas.

IBGE also publishes the Malha Municipal, which is the map that goes with this list. We use the list rather than the map because this is meant to be a lightweight table of names and codes, and the map comes with geometry.

What the dataset contains

Each edition is a ZIP of spreadsheets: one sheet for municipalities, one for districts and one for subdistricts, each in .xls and .ods. We use the district sheet, which has one row per district and also carries the municipality and state that the district belongs to. Every municipality has at least one district, so this sheet lists all three levels.

The columns that we use are in every edition, with the same names:

  • UF: two-digit code of the state
  • Nome_UF: name of the state
  • Código Município Completo: seven-digit code of the municipality, which starts with the state code
  • Nome_Município: name of the municipality
  • Código de Distrito Completo: nine-digit code of the district, which starts with the municipality code
  • Nome_Distrito: name of the district

The editions are otherwise not alike:

Year File Published Reference date in the sheet Districts Municipalities Layout of the district sheet
2020 DTB_2020_v2.zip 2021-02-25 not given 10,631 5,570 header on the first row; has mesoregion and microregion columns
2021 DTB_2021.zip 2022-02-22 not given 10,649 5,570 as 2020
2022 DTB_2022.zip 2023-03-15 21/12/2022 10,670 5,570 title rows above the header; has mesoregion and microregion columns
2023 DTB_2023.zip 2024-12-18 22/11/2024 10,724 5,570 title rows; no mesoregion or microregion columns; files are in a DTB_2023/ folder
2024 DTB_2024.zip 2025-04-30 31/12/2024 10,740 5,571 as 2023 but not in a folder; an OBS column, and working columns to the right of the table
2025 DTB_2025.zip 2026-03-26 31/12/2025 10,751 5,571 as 2023 but not in a folder

The sheets are named RELATORIO_DTB_BRASIL_DISTRITO until 2023 and RELATORIO_DTB_BRASIL_<year>_DISTRITOS from 2024. The 2020 file is a second version published by IBGE, which is why it is called "v2". In the 2022 edition, the municipality and subdistrict files that are named .ods are really Excel files.

Key changes

What changed from one edition to the next. No municipality has been removed, no district has moved to another municipality, and the states have not changed.

  • 2021: 18 districts created; 7 districts renamed.
  • 2022: 28 districts created and 7 removed; 2 districts renamed. Santo Antônio do Leverger (5107800, Mato Grosso) renamed Santo Antônio de Leverger.
  • 2023: 54 districts created; 11 districts renamed. Municipalities renamed: Gracho Cardoso (2802601, Sergipe) to Graccho Cardoso, Una (2932507, Bahia) to Unas, and Barão de Monte Alto (3105509, Minas Gerais) to Barão do Monte Alto.
  • 2024: the new municipality Boa Esperança do Norte (5101837, Mato Grosso), with one district (510183705); 19 districts created and 3 removed. Unas (2932507, Bahia) renamed back to Una.
  • 2025: 12 districts created and 1 removed; 6 districts renamed. Municipalities renamed: São Luiz (1400605, Roraima) to São Luiz do Anauá, Açu (2400208, Rio Grande do Norte) to Assú, and Arês (2401206, Rio Grande do Norte) to Arez.

How we use the dataset in Trase

It is the source of brazil_ibge_states_gold, brazil_ibge_municipalities_gold and brazil_ibge_districts_gold, which say which states, municipalities and districts existed in each year and give each of them a Trase ID.

How to fetch the data from the source

  • Update frequency: yearly
  • Next expected update: the 2026 edition, probably between February and April 2027

The editions are at https://geoftp.ibge.gov.br/organizacao_do_territorio/estrutura_territorial/divisao_territorial/, in one folder per year. IBGE describes the product at https://www.ibge.gov.br/geociencias/organizacao-do-territorio/divisao-regional/23701-divisao-territorial-brasileira.html.

We have a script which downloads each ZIP and converts its district sheet to Parquet:

python trase/data/brazil/spatial/boundaries/ibge/divisao_territorial/bronze/divisao_territorial_districts_YYYY.py

It writes to trase/data_pipeline/trase-storage-local/, which is where DBT looks with --target local. Add --upload to write to S3 as well. The files are:

  • s3://trase-storage/brazil/spatial/boundaries/ibge/divisao_territorial/originals/DTB_<year>.zip: the ZIP as published
  • s3://trase-storage/brazil/spatial/boundaries/ibge/divisao_territorial/bronze/divisao_territorial_districts_<year>.parquet: the district sheet, with IBGE's column names and every value as text

The script records the SHA-256 of each ZIP. If IBGE publishes a file again with different contents then the script stops, and somebody has to look at what changed before updating the checksum. It does not replace a file on S3 with a different one unless it is run with --force.

To add an edition: add it to RELEASES in the script, add its two files to _sources.yml and add them to the brazil_ibge_divisao_territorial_silver model, then run the DBT pipeline.

The script that is used to process/clean the dataset.

The conversion to Parquet is done by the download script, trase/data/brazil/spatial/boundaries/ibge/divisao_territorial/bronze/divisao_territorial_districts_YYYY.py. It does not clean anything: it removes the title rows above the header, and the columns that have no header or that repeat another column.

The DBT model brazil_ibge_divisao_territorial_silver combines all editions into one table, with one row per district per year. The gold models brazil_ibge_states_gold, brazil_ibge_municipalities_gold and brazil_ibge_districts_gold take one level each from it, give each entity a Trase ID and add an unknown row per year.

History

  • 2026-09: 2020 to 2025 editions downloaded by Harry using the script

Acceptance Criteria

  • Every district code has nine digits, is not repeated within a year, and starts with the code of its municipality and state. The download script checks this.
  • There are 27 states in every year.
  • There are 5,570 municipalities up to 2023 and 5,571 from 2024. The number changes rarely: a new edition should differ from the one before by no more than a few municipalities.
  • The number of districts grows by between 10 and 60 a year. A new edition should be within about 1% of the one before.

{% enddocs %}

{% docs brazil_ibge_states_gold %}

States of Brazil by year

The states of Brazil (26 states and the Distrito Federal) in each year from 2020 to 2025, according to IBGE's Divisão Territorial Brasileira, with their Trase IDs. There is one row per state per year, so filter by year to get the states of one year.

What the dataset contains

  • year: the edition of the Divisão Territorial Brasileira
  • trase_id: BR- followed by the IBGE state code, for example BR-51
  • name: name as IBGE writes it, for example "Mato Grosso"
  • ibge_state_code: two-digit IBGE code

How the Trase ID is made. It is built from the IBGE code, which is how Trase IDs for Brazilian states are defined. Nothing is matched by name.

The unknown state. Each year also has a row for an unknown state, with the Trase ID BR-XX, the name "Unknown state" and no IBGE code. It cannot be confused with a real state, whose ID always ends in two digits.

IBGE's list does not have the abbreviations of the states (MT, SP and so on), so neither does this table.

How we use the dataset in Trase

As the list of states that brazil_ibge_municipalities_gold and brazil_ibge_districts_gold refer to.

{% enddocs %}

{% docs brazil_ibge_municipalities_gold %}

Municipalities of Brazil by year

The municipalities of Brazil in each year from 2020 to 2025, according to IBGE's Divisão Territorial Brasileira, with their Trase IDs and the state that each is in. There is one row per municipality per year, so filter by year to get the municipalities of one year. A municipality that did not exist in a year has no row for that year: Boa Esperança do Norte (BR-5101837) appears from 2024.

What the dataset contains

  • year: the edition of the Divisão Territorial Brasileira
  • trase_id: BR- followed by the IBGE municipality code, for example BR-5107925
  • name: name as IBGE writes it, for example "São Félix do Xingu"
  • ibge_municipality_code: seven-digit IBGE code
  • state_trase_id: Trase ID of the state, which is in brazil_ibge_states_gold for the same year
  • ibge_state_code: two-digit IBGE code of the state

How the Trase ID is made. It is built from the IBGE code, which is how Trase IDs for Brazilian municipalities are defined. Nothing is matched by name.

The unknown municipality. Each year also has a row for an unknown municipality, with the Trase ID BR-XXXXXXX, the name "Unknown municipality", the state BR-XX and no IBGE codes. It cannot be confused with a real municipality, whose ID always ends in seven digits.

Names keep IBGE's capitals and accents. The older municipality dictionary writes names in capitals without accents, so join on trase_id and not on the name. IBGE also changes the spelling of a name now and then, so a municipality can have different names in different years; the changes are listed under "Key changes" below.

How we use the dataset in Trase

To know which municipalities existed in a year, and to go from an IBGE municipality code to a Trase ID. It is meant to take over from the municipality dictionary (brazil/dictionaries/municipality.csv), which is edited by hand and has no years.

{% enddocs %}

{% docs brazil_ibge_districts_gold %}

Districts of Brazil by year

The districts of Brazil in each year from 2020 to 2025, according to IBGE's Divisão Territorial Brasileira, with the municipality and state that each is in. A district (distrito) is a subdivision of a municipality. Every municipality has at least one, which usually has the same name as the municipality. There is one row per district per year, so filter by year to get the districts of one year.

What the dataset contains

  • year: the edition of the Divisão Territorial Brasileira
  • trase_id: BR- followed by the IBGE district code, for example BR-110001515
  • name: name as IBGE writes it, for example "Filadélfia d'Oeste"
  • ibge_district_code: nine-digit IBGE code
  • municipality_trase_id: Trase ID of the municipality, which is in brazil_ibge_municipalities_gold for the same year
  • ibge_municipality_code: seven-digit IBGE code of the municipality
  • state_trase_id: Trase ID of the state, which is in brazil_ibge_states_gold for the same year
  • ibge_state_code: two-digit IBGE code of the state

How the Trase ID is made. Trase had no IDs for Brazilian districts before this table. We follow the way that IDs are made for Brazilian states and municipalities: BR- followed by the IBGE code.

The unknown district. Each year also has a row for an unknown district, with the Trase ID BR-XXXXXXXXX (nine X), the name "Unknown district", the municipality BR-XXXXXXX, the state BR-XX and no IBGE codes. It cannot be confused with a real district, whose ID always ends in nine digits, or with the unknown municipality, which has seven X.

IBGE also lists subdistricts, which are subdivisions of some districts. They are not in this table.

How we use the dataset in Trase

Not used in a supply chain model yet.

{% enddocs %}