Todo sistema que emite nota fiscal, gera folha de pagamento ou cruza endereço com dado público acaba precisando do código IBGE do município. É um número de 7 dígitos que identifica cada cidade brasileira sem ambiguidade, coisa que o nome nunca fez. Existem cinco municípios chamados Bom Jesus, e “Santa Bárbara d’Oeste” chega ao seu banco escrito de pelo menos três jeitos. Neste guia, você vai ver como o código IBGE é montado e onde ele é obrigatório. Depois, vai consultar a API pública do IBGE e chegar ao número a partir de um CEP ou de um nome digitado.
O que é o código IBGE e como ele é formado
O código IBGE de município faz parte da Divisão Territorial Brasileira, a lista oficial de estados, municípios e distritos mantida pelo Instituto Brasileiro de Geografia e Estatística. O instituto atribui um número a cada Unidade da Federação e a cada município. Esse número não muda quando a cidade troca de nome, e por isso ele serve como chave estável em qualquer banco de dados.
A tabela IBGE de municípios tinha 5.571 registros em setembro de 2026, segundo a própria API do instituto. A conta inclui Brasília (5300108), que representa o Distrito Federal, e Fernando de Noronha (2605459), distrito estadual de Pernambuco com código próprio.
Os 7 dígitos: UF, município e dígito verificador
O código IBGE tem três partes, sempre nesta ordem:
- Dois dígitos da UF. São Paulo é 35, Minas Gerais é 31, Bahia é 29.
- Quatro dígitos do município dentro da UF. Na origem eles seguiram a ordem alfabética, mas municípios criados ou renomeados depois quebram essa ordem. Em São Paulo, Zacarias tem o código 3557154, e Chavantes (3557204) e Estiva Gerbi (3557303) vêm depois dele.
- Um dígito verificador. É um número calculado a partir dos seis anteriores, como os dois últimos dígitos do CPF. Ele pega qualquer dígito digitado errado e a maior parte das trocas entre dígitos vizinhos.
Pegue o código IBGE da capital paulista, 3550308. O “35” indica São Paulo, o “5030” identifica a cidade dentro do estado e o “8” final é o dígito verificador, calculado a partir de 355030. Lendo assim, você confere se a cidade pertence à UF informada sem chamar serviço nenhum.
Código IBGE da UF e da região
O primeiro dígito da UF também carrega informação: ele indica a região. Assim, todo código que começa com 4 pertence ao Sul, e todo código que começa com 5 pertence ao Centro-Oeste. A tabela abaixo reúne os 27 códigos de UF.
| Região (1º dígito) | UFs e códigos IBGE |
|---|---|
| 1 Norte | RO 11, AC 12, AM 13, RR 14, PA 15, AP 16, TO 17 |
| 2 Nordeste | MA 21, PI 22, CE 23, RN 24, PB 25, PE 26, AL 27, SE 28, BA 29 |
| 3 Sudeste | MG 31, ES 32, RJ 33, SP 35 |
| 4 Sul | PR 41, SC 42, RS 43 |
| 5 Centro-Oeste | MS 50, MT 51, GO 52, DF 53 |
Repare que a numeração tem buracos: não existe UF 34 nem 36, por exemplo. Por isso, nenhuma validação deve supor sequência contínua. Esse mesmo código IBGE de dois dígitos aparece no campo cUF da NF-e. Ele também abre os 44 dígitos da chave de acesso da NF-e, então merece uma tabela fixa no sistema.
Como calcular o dígito verificador
O dígito verificador usa pesos alternados 1 e 2 sobre os seis primeiros dígitos. Quando um produto passa de 9, você soma os algarismos dele (12 vira 1 + 2). Depois, soma tudo e calcula quanto falta para a próxima dezena. O resultado é o sétimo dígito.
Com São Paulo fica assim: 3×1=3, 5×2=10 (vira 1), 5×1=5, 0×2=0, 3×1=3, 0×2=0. A soma é 12, faltam 8 para chegar a 20, e o 8 é o dígito. Se a soma já cair numa dezena exata, o dígito é 0.
def dv_ibge(codigo6: str) -> int:
soma = 0
for i, ch in enumerate(codigo6):
produto = int(ch) * (1 if i % 2 == 0 else 2)
soma += produto // 10 + produto % 10 # 10 vira 1 + 0
return (10 - soma % 10) % 10
# Nove códigos oficiais fogem da regra do dígito
EXCECOES = {2201919, 2201988, 2202251, 2611533, 3117836,
3152131, 4305871, 5203939, 5203962}
EXTERIOR = "9999999" # destinatário no exterior (NF-e), fora do IBGE
def codigo_ibge_valido(codigo: str, aceita_exterior: bool = False) -> bool:
if len(codigo) != 7 or not codigo.isdigit():
return False
if codigo == EXTERIOR:
return aceita_exterior
if int(codigo) in EXCECOES:
return True
return dv_ibge(codigo[:6]) == int(codigo[6])
print(codigo_ibge_valido("3550308")) # True, São Paulo
print(codigo_ibge_valido("3550307")) # False, dígito trocado
print(codigo_ibge_valido("9999999", aceita_exterior=True)) # True, NF-e
Atenção: aplicamos o cálculo à lista completa da API do IBGE, e nove códigos oficiais não passaram. Entre eles estão Bom Princípio do Piauí (2201919), Quixaba (2611533) e Coronel Barros (4305871). Sem a lista de exceção, seu sistema recusa cidades que existem de verdade.
O parâmetro aceita_exterior fica desligado por padrão, porque 9999999 só vale nos campos de endereço da NF-e. Em cadastro comum, ele deve ser recusado.
O cálculo serve como filtro rápido no front-end ou na importação de planilhas, mas só diz que o número é bem formado. A confirmação de que o código IBGE existe vem da tabela oficial. Antes de chegar nela, vale ver onde esse número é cobrado, porque é isso que define onde validar.
Onde o código IBGE do município é exigido
O código aparece em quase todo documento eletrônico que tem endereço. Na maioria deles, o sistema recusa o envio quando o número não bate com a UF ou quando o dígito está errado.
NF-e e NFC-e
No leiaute da NF-e (nota fiscal eletrônica), os códigos IBGE de UF e de município aparecem em mais de um grupo:
- cUF, na identificação da nota, com o código de dois dígitos da UF do emitente;
- cMunFG, com o município onde a operação aconteceu (o “fato gerador” do imposto);
- cMun, no endereço do emitente e no do destinatário, cada um acompanhado do nome (xMun) e da UF.
A NFC-e (modelo 65), nota do varejo, usa os mesmos campos.
A SEFAZ, a secretaria da fazenda estadual que autoriza a nota, confere se o código tem dígito válido e se os dois primeiros dígitos batem com a UF informada. Ela aceita os nove códigos da lista de exceção, então o seu validador precisa aceitá-los também. Quando o destinatário está no exterior, o leiaute pede o código 9999999, o nome “EXTERIOR” e a UF “EX”. Uma validação que só aceita códigos da tabela do IBGE quebra aqui. O guia de automação fiscal para evitar rejeições na NF-e mostra como esses erros de cadastro viram rejeição e como evitá-los antes do envio.
NFS-e, eSocial e SPED
Na NFS-e (nota fiscal de serviço eletrônica) do padrão nacional, o código IBGE também identifica o município emissor e o local da prestação do serviço. Como o ISS, o imposto municipal sobre serviços, pode ser devido em município diferente do endereço do prestador, um código trocado pode mandar o imposto para a prefeitura errada.
No eSocial, os eventos que levam endereço pedem o código do município no campo codMunic, com os mesmos 7 dígitos. É o caso dos eventos de cadastramento inicial e de admissão, no endereço do trabalhador. A documentação técnica do eSocial traz os leiautes e as tabelas de validação de cada versão.
No SPED, a EFD ICMS/IPI (a escrituração fiscal digital entregue ao fisco) traz o campo COD_MUN no registro de abertura (0000) e no cadastro de participantes (registro 0150).
Código IBGE em cadastros, BI e cruzamento com dado público
Fora do mundo fiscal, o código resolve o problema clássico de cruzar bases. Dados de população, PIB municipal e boa parte dos indicadores públicos usam o código IBGE como chave. Se o seu CRM guarda só o nome da cidade, cada cruzamento vira um exercício de adivinhação. Com o código, é um join direto.
Quando o código chega de uma planilha ou de um sistema legado, vale confirmar em lote que ele existe e a que cidade pertence. A API do IBGE do Hub do Desenvolvedor devolve os dados do município a partir do código, em JSON ou XML. O retorno já vem estruturado, pronto para gravar no cadastro. Crie uma conta de teste e veja a resposta no seu próprio ambiente.
API de localidades do IBGE: endpoints e formato de resposta
O IBGE mantém em servicodados.ibge.gov.br uma API pública e gratuita, que dispensa autenticação. A parte que interessa aqui é a de localidades, versão 1. A documentação oficial da API de localidades lista todos os recursos. Para quem busca o código IBGE, os mais usados são estes:
/api/v1/localidades/estadosdevolve as 27 UFs com id, sigla, nome e região;/api/v1/localidades/estados/SP/municipiosdevolve os municípios de uma UF (aceita a sigla ou o código 35);/api/v1/localidades/municipiosdevolve os 5.571 municípios de uma vez;/api/v1/localidades/municipios/3550308devolve um município pelo código.
Como a resposta vem estruturada
Por padrão, cada município vem com o código IBGE e duas hierarquias regionais aninhadas. A antiga vai de microrregião a mesorregião, UF e região. A atual, criada em 2017, vai de região imediata a região intermediária, UF e região. As duas levam à mesma UF, por caminhos diferentes.
O parâmetro view=nivelado achata tudo num objeto só, com chaves como municipio-id, municipio-nome, UF-sigla e regiao-nome. Para montar uma tabela local, o formato nivelado é bem mais cômodo. Além disso, orderBy=nome ordena a lista pelo nome.
Duas armadilhas da API do IBGE
A primeira armadilha aparece quando o código não existe. A consulta a /municipios/9999999 responde HTTP 200 com uma lista vazia, e não 404. Quem testa só o status da resposta conclui que deu certo e segue com um município fantasma.
A segunda é mais sutil. O município de Boa Esperança do Norte (MT), código 5101837, um dos mais recentes da tabela, vem com microrregiao igual a null. A divisão antiga continua na API para os municípios antigos, mas deixou de receber municípios novos depois de 2017. Por isso, um script que percorre m["microrregiao"]["mesorregiao"]["UF"]["sigla"] quebra justamente nele. Pegue a UF pelo ramo da região imediata ou use a visão nivelada, que traz UF-sigla preenchida para todos.
Na prática: trate lista vazia como “município não encontrado” e nunca leia a UF pela microrregião. São duas linhas de código que evitam um bug que só aparece em produção, no dia em que um cliente de Boa Esperança do Norte (MT) se cadastrar.
Cache local da tabela IBGE de municípios
A tabela muda pouco. Município novo aparece de tempos em tempos, e renomeação acontece algumas vezes por década. Consultar a API do IBGE a cada formulário preenchido acrescenta latência à toa e cria uma dependência externa que você não precisa ter.
O caminho mais robusto é baixar a lista nivelada e guardá-la num arquivo JSON ou numa tabela do banco. Uma rotina agendada, mensal ou trimestral, cuida da atualização. Se você quer revisar as opções de expiração e invalidação, o artigo sobre cache e suas estratégias cobre os modelos mais comuns. O exemplo abaixo usa o fetch nativo, que existe a partir do Node.js 18, carrega a lista e monta um índice por código IBGE:
const URL_IBGE =
'https://servicodados.ibge.gov.br/api/v1/localidades/municipios?view=nivelado';
async function carregarMunicipios() {
const resp = await fetch(URL_IBGE);
if (!resp.ok) throw new Error(`IBGE respondeu ${resp.status}`);
const lista = await resp.json();
const porCodigo = new Map();
for (const m of lista) {
porCodigo.set(String(m['municipio-id']), {
nome: m['municipio-nome'],
uf: m['UF-sigla'],
});
}
return porCodigo;
}
carregarMunicipios().then((mapa) => {
console.log(mapa.size); // 5571 em setembro de 2026
console.log(mapa.get('3545803')); // { nome: "Santa Bárbara d'Oeste", uf: 'SP' }
});
Na rotina de atualização, compare a lista nova com a anterior antes de sobrescrever. Se o total cair muito ou a resposta vier vazia, mantenha a versão antiga e dispare um alerta. Uma API fora do ar não pode apagar a sua tabela.
Municípios novos e renomeados
Quando uma cidade muda de nome, o código IBGE continua o mesmo. Embu virou Embu das Artes e Parati passou a se chamar Paraty, mas os códigos 3515004 e 3303807 não mudaram. Esse é o melhor argumento para guardar o código, e não o nome, como chave do cadastro.
Com município novo, o problema é o contrário. Ele recebe código próprio e aparece na API quando o IBGE atualiza a divisão territorial, e uma tabela congelada há anos não reconhece os endereços dessa cidade. Por isso, o comparativo da rotina de atualização precisa listar os códigos que entraram e os que saíram, e avisar alguém quando isso acontecer.
Código IBGE pelo CEP e pelo nome do município
Na vida real, quase ninguém digita o código IBGE. O usuário informa um CEP ou escreve o nome da cidade, e o sistema precisa chegar ao número.
Do CEP ao município e ao código IBGE
O CEP é o caminho mais confiável, porque vem de um cadastro postal e não de digitação livre. O fluxo tem três passos: consultar o CEP, obter o município e a UF, e ler o código IBGE correspondente. Várias APIs de CEP já trazem o código na mesma resposta, o que dispensa a consulta à tabela de municípios.
A API de consulta de CEP do Hub segue essa linha. A página da consulta de CEP informa que o retorno traz o endereço completo com códigos IBGE. Timeouts, formato do CEP e tratamento de CEP inexistente estão no guia completo de API de consulta de CEP. Já o comparativo das melhores APIs de CEP mostra o que cada fornecedor devolve.
Mesmo quando o código vem pronto, confira com a sua tabela local. Se o código IBGE pelo CEP não existe no cache, algo está errado na origem. O mesmo vale quando os dois primeiros dígitos não batem com a UF do endereço. Nos dois casos, marque o cadastro para revisão.
Dica: CEP de município que acabou de ser criado pode demorar a aparecer nas bases postais com a cidade nova. Durante esse intervalo, a consulta do CEP devolve a cidade de origem. Quando o endereço ficar numa área que acabou de se separar de outra cidade, vale confirmar o município com o cliente.
Normalizar o nome antes de procurar
Quando só existe o nome, procurar o código IBGE pela grafia exata falha com frequência. O mesmo município chega como “Santa Barbara D’Oeste”, “Santa Bárbara d’Oeste”, com apóstrofo tipográfico, ou “SANTA BARBARA DOESTE”. A própria tabela oficial alterna maiúscula e minúscula: Rondônia tem “Alta Floresta D’Oeste”, com D maiúsculo, enquanto São Paulo tem “Santa Bárbara d’Oeste”, com d minúsculo.
A solução é gerar uma chave normalizada dos dois lados, no cadastro e na tabela:
- separe cada letra do seu acento (decomposição Unicode) e descarte o acento;
- remova os apóstrofos e troque hífens por espaço;
- junte espaços repetidos num só;
- passe tudo para minúsculas.
Remover o apóstrofo, em vez de trocá-lo por espaço, é o que faz “d’Oeste” e “DOESTE” chegarem à mesma chave. Em JavaScript, String.prototype.normalize faz a decomposição; em Python, o módulo unicodedata cumpre o mesmo papel.
import unicodedata
import requests
URL = ("https://servicodados.ibge.gov.br/api/v1/localidades/"
"municipios?view=nivelado")
def chave(nome: str, uf: str) -> str:
texto = nome.replace("’", "'").replace("`", "'")
texto = unicodedata.normalize("NFKD", texto)
texto = "".join(c for c in texto if not unicodedata.combining(c))
texto = texto.lower().replace("'", "").replace("-", " ")
return f"{uf.upper()}|{' '.join(texto.split())}"
lista = requests.get(URL, timeout=30).json()
indice = {chave(m["municipio-nome"], m["UF-sigla"]): m["municipio-id"]
for m in lista}
print(indice.get(chave("Santa Barbara D'Oeste", "sp"))) # 3545803
print(indice.get(chave("SANTA BARBARA DOESTE", "SP"))) # 3545803
print(indice.get(chave("Pau D'Arco", "TO"))) # 1716307
A UF entra na chave de propósito. Pela nossa contagem na lista de setembro de 2026, 232 nomes se repetem em mais de uma UF e somam 505 municípios, cerca de 9% do total. Bom Jesus aparece cinco vezes, e Pau D’Arco existe no Pará e no Tocantins. Dentro de uma mesma UF, nenhum par de municípios terminou com a mesma chave depois da normalização.
Qual fonte usar para cada situação
| Fonte | Você informa | O que recebe | Quando usar | Cuidado |
|---|---|---|---|---|
| API de localidades do IBGE | código ou UF | nome, UF e hierarquia regional | carga e atualização da tabela | lista vazia com HTTP 200 para código inexistente |
| Tabela local em cache | código ou nome normalizado | o que você armazenou | validação em tempo real | precisa de rotina de atualização |
| API de CEP com código IBGE | CEP | endereço completo com código | cadastro e checkout | conferir o código contra a tabela |
| Digitação do usuário | nome da cidade | texto livre | só como último recurso | acentos, apóstrofos e homônimos |
Com a tabela em cache e a chave normalizada, falta escolher a origem do dado. Se o seu fluxo começa no CEP, a consulta de dados municipais do Hub e a consulta de CEP cobrem endereço e município numa única integração. Faça o teste gratuito e confira o formato da resposta.
Perguntas frequentes sobre o código IBGE
O código IBGE do município muda quando a cidade troca de nome?
Não. O código continua o mesmo depois de uma renomeação, como aconteceu com Embu das Artes (3515004) e Paraty (3303807). Só o nome precisa ser atualizado na sua tabela. Por isso, o código deve ser a chave do cadastro.
Quantos dígitos tem o código IBGE de município?
Sete. Os dois primeiros identificam a UF, os quatro seguintes identificam o município dentro da UF, e o último é o dígito verificador. O código da UF sozinho tem dois dígitos, como 35 para São Paulo.
A API do IBGE é gratuita e precisa de chave?
É gratuita e não pede autenticação. Os endpoints de localidades ficam em servicodados.ibge.gov.br/api/v1/localidades e devolvem JSON. Mesmo assim, guarde a tabela em cache em vez de consultar a cada requisição.
Como descobrir o código IBGE pelo CEP?
Consulte o CEP numa API que devolva o código IBGE junto com o endereço. Outra saída é usar o nome e a UF retornados para procurar na tabela do IBGE. Nos dois casos, confira se os dois primeiros dígitos batem com a UF do endereço.
Que código IBGE usar na NF-e para destinatário no exterior?
O leiaute da NF-e usa 9999999 no campo cMun, com o nome do município “EXTERIOR” e a UF “EX”. Esse valor não existe na tabela do IBGE e não passa no cálculo do dígito verificador. Por isso, a sua validação precisa tratá-lo como caso especial, aceito só nos campos de endereço da nota.
Resumo para levar ao código
Resumindo o caminho: guarde o código IBGE como chave e mantenha a tabela em cache com atualização agendada. Valide dígito e UF antes de gravar e prefira o CEP à digitação livre. Com essas quatro regras, a nota fiscal e o evento do eSocial deixam de voltar por causa de nome de cidade escrito errado.
Se o código IBGE ainda faz nota voltar rejeitada no seu sistema, comece pela origem do dado. A API de cidades do IBGE no Hub do Desenvolvedor entrega os dados municipais a partir do código IBGE. Ela faz parte do mesmo plano das APIs de CEP, CNPJ, CPF e frete. Crie sua conta, use os dias de teste grátis e compare o retorno com os cadastros que você já tem.
