Municípios

Retorna os municípios brasileiros publicados pelo IBGE: todos os municípios, ou só os de um estado quando stateCode é informado.

• Cada município (Municipality) é { code, name, stateCode }, onde code é o código IBGE de 7 dígitos. Ordenados por nome no locale "pt-BR".
• Só um stateCode omitido (ou undefined) pede a lista completa: null e '' retornam [].
• stateCode ignora maiúsculas/minúsculas e espaços nas pontas: 'sp' retorna os municípios de São Paulo, como 'SP' (até a 2.4.0 retornava []).
• Embute todos os 5571 municípios, os mesmos códigos da Divisão Territorial Brasileira 2025 do IBGE (data base 31/12/2025). Veja Tamanho do bundle para carregá-lo sob demanda via @brazilian-utils/brazilian-utils/get-municipalities.

import { getMunicipalities } from '@brazilian-utils/brazilian-utils';

// Retorna todos os municípios brasileiros (ordenados por nome).
getMunicipalities();
// [
//   { code: '5200050', name: 'Abadia de Goiás', stateCode: 'GO' },
//   { code: '3100104', name: 'Abadia dos Dourados', stateCode: 'MG' },
//   { code: '5200100', name: 'Abadiânia', stateCode: 'GO' },
//   { code: '3100203', name: 'Abaeté', stateCode: 'MG' },
//   { code: '1500107', name: 'Abaetetuba', stateCode: 'PA' },
//   ... mais 5566 itens
// ]

// Retorna todos os municípios do estado de São Paulo.
getMunicipalities('SP');
// [
//   { code: '3500105', name: 'Adamantina', stateCode: 'SP' },
//   { code: '3500204', name: 'Adolfo', stateCode: 'SP' },
//   { code: '3500303', name: 'Aguaí', stateCode: 'SP' },
//   { code: '3500402', name: 'Águas da Prata', stateCode: 'SP' },
//   { code: '3500501', name: 'Águas de Lindóia', stateCode: 'SP' },
//   ... mais 640 itens
// ]

getMunicipalities('ZZ'); // []

Fonte: IBGE Localidades

Busca um município brasileiro pelo código IBGE de 7 dígitos.

• Aceita o código como string ou número inteiro não negativo, com todo caractere que não é dígito removido da string.
• Retorna { code, name, stateCode } (Municipality), ou null quando o código não tem 7 dígitos ou não corresponde a nenhum município.

import { getMunicipalityByCode } from '@brazilian-utils/brazilian-utils';

getMunicipalityByCode('3550308');
// { code: '3550308', name: 'São Paulo', stateCode: 'SP' }

getMunicipalityByCode(3550308);
// { code: '3550308', name: 'São Paulo', stateCode: 'SP' }

getMunicipalityByCode('0000000'); // null (código desconhecido)
getMunicipalityByCode('123'); // null (não tem 7 dígitos)

Fonte: IBGE Localidades

Busca o código IBGE de 7 dígitos de um município brasileiro pelo nome e pela sigla do estado. É a versão offline e síncrona do get_code_by_municipality_name da biblioteca Python, que consulta a API do IBGE pela rede.

• O nome ignora acentos, cedilha e maiúsculas/minúsculas. Sequências de espaços viram um só e os espaços em volta são removidos, mas um nome escrito sem um espaço que o nome do IBGE tem não é encontrado ('saopaulo').
• Recebe um único objeto, { municipalityName, stateCode } (GetCodeByMunicipalityNameParams), com os dois campos obrigatórios. A sigla do estado ignora maiúsculas/minúsculas e espaços em volta, como em todo util que recebe UF. Ela é obrigatória, porque o mesmo nome pode ser de municípios de estados diferentes ('Bom Jesus' existe no PI, no RS e em outros estados).
• Retorna o código como string, ou null quando a sigla não é de um estado ou nenhum município daquele estado tem esse nome.
• Embute os 5571 municípios, a mesma tabela de getMunicipalityByCode. Veja Tamanho do bundle para carregá-la sob demanda via @brazilian-utils/brazilian-utils/get-code-by-municipality-name.

import { getCodeByMunicipalityName } from '@brazilian-utils/brazilian-utils';

getCodeByMunicipalityName({ municipalityName: 'Conceição do Coité', stateCode: 'Ba' }); // '2908408'
getCodeByMunicipalityName({ municipalityName: 'sao paulo', stateCode: 'sp' }); // '3550308'
getCodeByMunicipalityName({ municipalityName: 'Bom Jesus', stateCode: 'RS' }); // '4302303'
getCodeByMunicipalityName({ municipalityName: 'São Paulo', stateCode: 'RJ' }); // null (não há São Paulo no Rio de Janeiro)
getCodeByMunicipalityName({ municipalityName: 'Município Inexistente', stateCode: 'RS' }); // null

Fonte: IBGE Localidades

Lista os municípios brasileiros que usam um DDD (código de área), segundo a tabela da Anatel dos Códigos Nacionais em vigor.

• Aceita o DDD como o getAreaCodeInfo: string (com todo caractere que não é dígito removido) ou número inteiro não negativo.
• Retorna um array de { code, name, stateCode } (Municipality): primeiro os municípios do estado sede, depois os do outro estado em que o DDD entra, cada estado em ordem alfabética. Retorna [] quando o DDD não está em uso.

import { getMunicipalitiesByAreaCode } from '@brazilian-utils/brazilian-utils';

getMunicipalitiesByAreaCode(68).length; // 22 (todos os municípios do Acre)
getMunicipalitiesByAreaCode('(61)').length; // 13 (Brasília e 12 municípios de Goiás)
getMunicipalitiesByAreaCode('47').at(-1); // { code: '4122305', name: 'Rio Negro', stateCode: 'PR' }
getMunicipalitiesByAreaCode('20'); // []

Fonte: Resolução Anatel nº 749/2022, Códigos Nacionais da Anatel, tabela da Anatel dos Códigos Nacionais por município (21/09/2026).