Municipalities

Get the Brazilian municipalities published by the IBGE: every municipality, or only those of one state when stateCode is given.

• Each municipality (Municipality) is { code, name, stateCode }, where code is the 7-digit IBGE code. Sorted by name in the "pt-BR" locale.
• Only an omitted (or undefined) stateCode asks for the full list: null and '' return [].
• stateCode ignores letter case and surrounding whitespace: 'sp' returns the São Paulo municipalities, as 'SP' does (up to 2.4.0 it returned []).
• Embeds all 5571 municipalities, the same codes as the IBGE Divisão Territorial Brasileira 2025 (data base 31/12/2025). See Bundle size to lazy-load it via @brazilian-utils/brazilian-utils/get-municipalities.

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

// Return every Brazilian municipality (sorted by name).
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' },
//   ... 5566 more items
// ]

// Return every municipality of the São Paulo state.
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' },
//   ... 640 more items
// ]

getMunicipalities('ZZ'); // []

Source: IBGE Localidades

Look up a Brazilian municipality by its 7-digit IBGE code.

• Accepts the code as a string or a non-negative integer, with any non-digit characters of a string stripped.
• Returns { code, name, stateCode } (Municipality), or null when the code is not 7 digits long or matches no municipality.

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 (unknown code)
getMunicipalityByCode('123'); // null (not 7 digits)

Source: IBGE Localidades

Look up the 7-digit IBGE code of a Brazilian municipality by its name and the code of its state. It is the offline, synchronous counterpart of get_code_by_municipality_name in the Python library, which queries the IBGE API over the network.

• The name ignores accents, the cedilla and letter case. Runs of whitespace collapse and the surrounding whitespace is trimmed, but a name written without a space the IBGE name has does not match ('saopaulo').
• Takes one object, { municipalityName, stateCode } (GetCodeByMunicipalityNameParams), with both fields required. The state code ignores letter case and surrounding whitespace, as every util that takes a state does. It is required, since the same name can belong to municipalities of different states ('Bom Jesus' exists in PI, RS and other states).
• Returns the code as a string, or null when the state code is not a state or no municipality of that state has that name.
• Embeds the 5571 municipalities, the same table as getMunicipalityByCode. See Bundle size to lazy-load it 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 (no São Paulo in Rio de Janeiro)
getCodeByMunicipalityName({ municipalityName: 'Município Inexistente', stateCode: 'RS' }); // null

Source: IBGE Localidades

List the Brazilian municipalities that dial a given DDD (area code), from the Anatel table of the Códigos Nacionais in force.

• Accepts the DDD the way getAreaCodeInfo does: a string (any non-digit characters stripped) or a non-negative integer.
• Returns an array of { code, name, stateCode } (Municipality): the seat state's municipalities first, then those of the other state the DDD crosses into, each state's sorted by name. Returns [] when the DDD is not in use.

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

getMunicipalitiesByAreaCode(68).length; // 22 (every municipality of Acre)
getMunicipalitiesByAreaCode('(61)').length; // 13 (Brasília and 12 municipalities of Goiás)
getMunicipalitiesByAreaCode('47').at(-1); // { code: '4122305', name: 'Rio Negro', stateCode: 'PR' }
getMunicipalitiesByAreaCode('20'); // []

Source: Resolução Anatel nº 749/2022, Anatel Códigos Nacionais, Anatel table of the Códigos Nacionais by municipality (21/09/2026).