Municipalities

List

Returns the Brazilian municipalities published by the IBGE, sorted by name (pt-BR collation). It returns all of them, or those of one state.

Each entry has the 7-digit IBGE code, the name and the state code.
stateCode is matched ignoring case and surrounding whitespace: "sp" and " SP " return the 645 municipalities of São Paulo, as "SP" does. 2.4.0 matched case-sensitively and returned an empty list for "sp".
Only an omitted stateCode returns the full list. An empty or unknown code returns an empty list.
Each call returns a new array of new objects.
JavaScript also keeps getCities(state), deprecated, which returns only the names. It reads any falsy argument as the full list, where getMunicipalities returns an empty list for null and an empty string.

Parameter	Type	Required
`stateCode`	`StateCode`	no
returns	`Municipality[]`

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

Code: brazilian-utils/javascript

Try it with JavaScript getMunicipalities

Shared test cases (10) and the result in each library municipality.list

The cases, as JSON

Get by code

Looks up a municipality by its 7-digit IBGE code.

code may be a string or a non-negative integer.
A string has every character that is not a digit removed first, as in 2.4.0: "355-030-8" and "3550308 SP" both find São Paulo.
A negative or fractional number is not read as a code and returns null.
The result has the code, the name and the state code. Each call returns a new object.
Returns null when the digits are not 7 or match no municipality.
JavaScript also keeps getMunicipality({ code }), deprecated, which returns a Promise of a [name, stateCode] pair (or null) instead of the object.

Parameter	Type	Required
`code`	`string \| number`	yes
returns	`Municipality \| null`

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

Code: brazilian-utils/javascript

Try it with JavaScript getMunicipalityByCode

Shared test cases (12) and the result in each library municipality.getByCode

The cases, as JSON

Get code by name

Returns the 7-digit IBGE code of a municipality, given its name and the code of its state.

Takes one object with municipalityName and stateCode, both required. The same name can belong to municipalities of different states (Bom Jesus exists in PI, RS and other states), so the state is required.
The name ignores accents, the cedilla and letter case (ß reads as SS). Runs of whitespace collapse into one space and the surrounding whitespace is trimmed, but a name written without a space the IBGE name has does not match (saopaulo). The hyphen of a name is kept.
stateCode ignores letter case and surrounding whitespace, as every function that takes a state does.
Returns the code as a string. Returns null when the state code is not a state, when no municipality of that state has that name, when the name is not a string or is empty, and when the parameters are missing or malformed.
The JavaScript function is synchronous and offline: it reads the bundled table of 5,571 municipalities, the same as municipality.getByCode. The Python function of the same name (get_code_by_municipality_name(municipality_name, uf)) asks the IBGE API over the network.
JavaScript also keeps getMunicipality({ municipalityName, uf }), deprecated, which answers the same way and returns a Promise.

Parameter	Type	Required
`params`	`GetCodeByMunicipalityNameParams`	yes
`params.municipalityName`	`string`	yes
`params.stateCode`	`string`	yes
returns	`string \| null`

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

Code: brazilian-utils/javascript

Try it with JavaScript getCodeByMunicipalityName

Shared test cases (23) and the result in each library municipality.getCodeByName

The cases, as JSON

List by area code

Returns the municipalities that dial a DDD (area code, the Código Nacional of the Plano Geral de Numeração).

areaCode is read as areaCode.getInfo reads it: a string with every non-digit removed ("(61)" works), or a non-negative integer.
Returns an empty list for a DDD outside the 67 in use, and for a negative or fractional number.
Order: first the municipalities of the state the DDD is seated in, then those of the other states in AreaCodeInfo.stateCodes. Inside each state, by name (pt-BR collation).
Four DDDs cross a state border: 61 also covers 12 municipalities of Goiás, 42 covers Porto União (SC), 47 covers Rio Negro (PR) and 49 covers Barracão (PR).
Each entry has the 7-digit IBGE code, the name and the state code. Each call returns a new array of new objects.

Parameter	Type	Required
`areaCode`	`string \| number`	yes
returns	`Municipality[]`

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'); // []