Crosswalk Territorial do Brasil
Os códigos IBGE, TSE e da Receita Federal reconciliados — mais CEP para município, resolvido por endereço observado.
5.571
municípios vigentes
931.499
CEPs resolvidos para município
Números de setembro de 2026, conferidos com a documentação do listing.
1. O problema
O Brasil tem pelo menos quatro sistemas de código territorial que não conversam entre si: o IBGE de 7 dígitos (o padrão estatístico), o IBGE de 6 dígitos (usado por DATASUS e sistemas legados), o do TSE (todo dado eleitoral) e o da Receita Federal — a ponte para o cadastro de CNPJ, o mesmo que o Tesouro republica como "código SIAFI".
Cruzar dado eleitoral com dado econômico, ou dado de saúde com cadastro de empresas, exige traduzir entre eles. Todo time de dados no Brasil já perdeu uma semana com isso.
E há o segundo problema, mais silencioso: CEP não é município. A maior parte do mercado resolve CEP por faixa numérica, o que funciona quase sempre e falha sem avisar quando não funciona.
2. O que existe publicado, e o que não existe
Cada órgão publica a sua própria tabela, e todas estão corretas. O IBGE publica a divisão territorial, o TSE publica os seus códigos, a Receita mantém a tabela de órgãos e municípios.
O que não existe publicado é a tabela que liga um ao outro — nem a série histórica que diz o que aconteceu com um município que mudou de código, de nome ou de estado.
3. Como o dado é construído
Todo cruzamento é por código oficial, nunca por nome. Não há correspondência aproximada em lugar nenhum da lógica. Nomes de município divergem entre órgãos em dezenas de casos — acentuação, abreviatura, artigo — e casar por nome produz erro que não aparece em teste de contagem.
A ponte IBGE ↔ Receita é validada contra uma publicação independente. O Tesouro publica o mesmo código por outro caminho, e os dois concordam em 5.570 de 5.570. A verificação roda a cada publicação: são dois órgãos publicando o mesmo dado por vias independentes, e é validação real, não conferência interna.
A resolução de CEP é observada, não inferida. Cada CEP é atribuído ao município onde os endereços dele efetivamente caem, contados a partir do cadastro nacional de endereços. Isso permite declarar duas coisas que uma tabela de faixas não consegue:
- que fração dos endereços cai no município atribuído
- quais CEPs cruzam fronteira municipal — o que acontece de fato
A série histórica preserva o nome e a UF da época, e distingue "a fonte escreveu sem acento" de "nós normalizamos" — duas coisas que, sem uma coluna para separá-las, ficam indistinguíveis.
4. O que este dado NÃO faz
- Não converte entre duas edições históricas. Cobre qualquer ano para o atual.
- Não resolve endereço, apenas CEP para município.
- Não tem população por ano. Traz a dos Censos de 2022 — e um município não tem: Boa Esperança do Norte/MT foi instalado depois do recenseamento. O dado declara isso em vez de deixar a soma não fechar em silêncio.
- São 5.571 municípios, não 5.570. O número que circula está desatualizado desde 1º de janeiro de 2025.
5. Como se sabe que está certo
Além da validação cruzada entre Receita e Tesouro:
A soma dos pesos de conversão dá exatamente 1 por origem, o que garante que converter uma grandeza somável preserva o total.
Existe uma declaração de qualidade versionada, conferida contra o dado a cada publicação. Quando o dataset afirma um número sobre si mesmo, um teste mede e compara.
Toda cobertura parcial é declarada em coluna própria. Se um município não tem código do Tesouro, há um booleano dizendo isso — não um nulo para o consumidor interpretar.
6. Acesso
Publicado no Snowflake Marketplace, gratuito.
Fontes: IBGE, Tribunal Superior Eleitoral, Receita Federal e Secretaria do Tesouro Nacional — dados abertos federais, de uso livre. A atribuição de cada uma acompanha o dado.
7. Encontrou um problema, ou quer saber quando o dado muda
Erro reportado é mais útil que erro não encontrado: hi@insigne.tech.
A newsletter. Toda mudança no dado sobe a versão do dataset e entra num changelog, que sai por lá. Mas ela não é só isso: é também por onde saem os bastidores de como estes conjuntos de dados são construídos, e o que aprendemos trabalhando com dado público — que quase nunca chega pronto.
Um e-mail ocasional, sem ruído.
O dado público raramente chega no formato em que se precisa dele. Este crosswalk existe porque um projeto precisou dele e ele não existia.
Se o seu caso é parecido, é disso que tratamos.