States (UF)

Brazilian states (unidades federativas): codes, names, IBGE codes, capitals, regions and time zones.

List

Returns the 27 Brazilian federative units, sorted by name (pt-BR collation).

Each entry has the two-letter code, the name, the region code and name, and the 2-digit IBGE code.
Each call returns a new array of new objects.

Parameter	Type	Required
returns	`State[]`

Get all Brazilian states, each with its two-letter code, name, region code, region name and 2-digit IBGE code (cUF).

Sorted by name in the "pt-BR" locale.
Exports the State, StateCode and StateName types. State is a discriminated union: narrowing it by code also narrows the other fields.

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

getStates();
// [
//   { code: 'AC', name: 'Acre', regionCode: 'N', regionName: 'Norte', ibgeCode: 12 },
//   { code: 'AL', name: 'Alagoas', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 27 },
//   { code: 'AP', name: 'Amapá', regionCode: 'N', regionName: 'Norte', ibgeCode: 16 },
//   { code: 'AM', name: 'Amazonas', regionCode: 'N', regionName: 'Norte', ibgeCode: 13 },
//   { code: 'BA', name: 'Bahia', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 29 },
//   { code: 'CE', name: 'Ceará', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 23 },
//   { code: 'DF', name: 'Distrito Federal', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 53 },
//   { code: 'ES', name: 'Espírito Santo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 32 },
//   { code: 'GO', name: 'Goiás', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 52 },
//   { code: 'MA', name: 'Maranhão', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 21 },
//   { code: 'MT', name: 'Mato Grosso', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 51 },
//   { code: 'MS', name: 'Mato Grosso do Sul', regionCode: 'CO', regionName: 'Centro-Oeste', ibgeCode: 50 },
//   { code: 'MG', name: 'Minas Gerais', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 31 },
//   { code: 'PA', name: 'Pará', regionCode: 'N', regionName: 'Norte', ibgeCode: 15 },
//   { code: 'PB', name: 'Paraíba', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 25 },
//   { code: 'PR', name: 'Paraná', regionCode: 'S', regionName: 'Sul', ibgeCode: 41 },
//   { code: 'PE', name: 'Pernambuco', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 26 },
//   { code: 'PI', name: 'Piauí', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 22 },
//   { code: 'RJ', name: 'Rio de Janeiro', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 33 },
//   { code: 'RN', name: 'Rio Grande do Norte', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 24 },
//   { code: 'RS', name: 'Rio Grande do Sul', regionCode: 'S', regionName: 'Sul', ibgeCode: 43 },
//   { code: 'RO', name: 'Rondônia', regionCode: 'N', regionName: 'Norte', ibgeCode: 11 },
//   { code: 'RR', name: 'Roraima', regionCode: 'N', regionName: 'Norte', ibgeCode: 14 },
//   { code: 'SC', name: 'Santa Catarina', regionCode: 'S', regionName: 'Sul', ibgeCode: 42 },
//   { code: 'SP', name: 'São Paulo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 35 },
//   { code: 'SE', name: 'Sergipe', regionCode: 'NE', regionName: 'Nordeste', ibgeCode: 28 },
//   { code: 'TO', name: 'Tocantins', regionCode: 'N', regionName: 'Norte', ibgeCode: 17 },
// ]

Source: IBGE Localidades

Code: brazilian-utils/javascript

Try it with JavaScript getStates

Shared test cases (1) and the result in each library state.list

The cases, as JSON

Get by ibge code

Returns the state whose 2-digit IBGE code (cUF, the code in the first field of a DF-e access key) matches 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: "35/SP" and " 35 " resolve to São Paulo.
A negative or fractional number is not read as a code and returns null.
The result has the code, name, region code, region name and IBGE code.
Returns null when the code matches no state.

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

Get the Brazilian state whose 2-digit IBGE code (cUF, the Código da Unidade da Federação) matches the given value.

This is the UF code in the first field of a DF-e access key (chave de acesso), the one isValidNfeKey covers.
Accepts a string or a non-negative integer, with any non-digit characters of a string stripped ('35/SP' is 35).
Returns null when the code matches no state. Exports the State type.

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

getStateByIbgeCode('35');
// { code: 'SP', name: 'São Paulo', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 35 }

getStateByIbgeCode(11);
// { code: 'RO', name: 'Rondônia', regionCode: 'N', regionName: 'Norte', ibgeCode: 11 }

getStateByIbgeCode('00'); // null
getStateByIbgeCode(-35); // null
getStateByIbgeCode(3.5); // null

Source: IBGE Localidades, Manual de Orientação do Contribuinte

Code: brazilian-utils/javascript

Try it with JavaScript getStateByIbgeCode

Shared test cases (12) and the result in each library state.getByIbgeCode

The cases, as JSON

Get capital

Returns the capital of a state, in the same shape municipality.getByCode returns: the 7-digit IBGE code, the name and the state code.

The match ignores case and surrounding whitespace: "to" and " TO " both give Palmas.
The Distrito Federal has no municipalities. Its capital is Brasília, with the code the IBGE gives the whole district (5300108).
Returns null for a string that is not a state code, and for a value that is not a string.
The State type has no capital field. The capital comes only from this function.
Each call returns a new object.

Parameter	Type	Required
`stateCode`	`string`	yes
returns	`Municipality \| null`

Get the capital of a Brazilian state, as the same { code, name, stateCode } (Municipality) that getMunicipalityByCode returns for it.

The match ignores case and surrounding whitespace. Returns null when no state matches.
The Distrito Federal is not divided into municipalities, but the IBGE codes it as a single one, Brasília, and that is its capital.

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

getStateCapital('SP'); // { code: '3550308', name: 'São Paulo', stateCode: 'SP' }
getStateCapital('to'); // { code: '1721000', name: 'Palmas', stateCode: 'TO' }
getStateCapital('DF'); // { code: '5300108', name: 'Brasília', stateCode: 'DF' }
getStateCapital('ZZ'); // null

Source: IBGE, Anuário Estatístico do Brasil, table 1.1.1.2 (state capitals, 2025)

Code: brazilian-utils/javascript

Try it with JavaScript getStateCapital

Shared test cases (15) and the result in each library state.getCapital

The cases, as JSON

Get code by name

Returns the two-letter code (sigla) of a state from its full name.

The match ignores accents, case and surrounding whitespace. Internal whitespace collapses into one space.
Only the full name matches. The code (SP) and a name written without its spaces (saopaulo) return null.
Returns null when no state matches.

Parameter	Type	Required
`name`	`string`	yes
returns	`StateCode \| null`

Get the two-letter code (sigla) of a Brazilian state from its full name.

The match ignores accents, case and surrounding whitespace; internal whitespace collapses into one space.
Returns null when no state matches. Exports the StateCode type.

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

getStateCodeByName('São Paulo'); // 'SP'
getStateCodeByName('sao paulo'); // 'SP'
getStateCodeByName('  Rio de Janeiro  '); // 'RJ'
getStateCodeByName('Neverland'); // null

Source: IBGE, API de Localidades, estados

Code: brazilian-utils/javascript

Try it with JavaScript getStateCodeByName

Shared test cases (20) and the result in each library state.getCodeByName

The cases, as JSON

Get name by code

Returns the full name of a state from its two-letter code (sigla).

The match ignores case and surrounding whitespace.
The legal time of Brazil is the one of Decreto 2.784/1913, as amended by Lei 11.662/2008 (revoked) and Lei 12.876/2013, which restored the zones of Acre and the south-west of Amazonas. The zone names come from the IANA database. Daylight saving time (Decreto 8.112/2013) is not a source of this function.
Returns null when no state matches.

Parameter	Type	Required
`code`	`string`	yes
returns	`StateName \| null`

Get the full name of a Brazilian state from its two-letter code (sigla).

The match ignores case and surrounding whitespace.
Returns null when no state matches. Exports the StateName type.

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

getStateNameByCode('SP'); // 'São Paulo'
getStateNameByCode('sp'); // 'São Paulo'
getStateNameByCode('  Rj  '); // 'Rio de Janeiro'
getStateNameByCode('ZZ'); // null

Source: IBGE, API de Localidades, estados

Code: brazilian-utils/javascript

Try it with JavaScript getStateNameByCode

Shared test cases (9) and the result in each library state.getNameByCode

The cases, as JSON

Get regions

Returns the five Grandes Regiões of the IBGE, sorted by their IBGE identifier: Norte (1), Nordeste (2), Sudeste (3), Sul (4) and Centro-Oeste (5).

Each entry has the region code (N, NE, SE, S, CO, the same regionCode every state carries), the name and the IBGE identifier.
The State type has no region identifier field. The identifier comes only from this function.
Each call returns a new array of new objects.

Parameter	Type	Required
returns	`Region[]`

Get the five Brazilian regions (Grandes Regiões), each with its code (the same regionCode every state carries), name and IBGE identifier, in the order of that identifier. Exports the Region and RegionCode types.

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

getRegions();
// [
//   { code: 'N', name: 'Norte', ibgeCode: 1 },
//   { code: 'NE', name: 'Nordeste', ibgeCode: 2 },
//   { code: 'SE', name: 'Sudeste', ibgeCode: 3 },
//   { code: 'S', name: 'Sul', ibgeCode: 4 },
//   { code: 'CO', name: 'Centro-Oeste', ibgeCode: 5 },
// ]

Source: IBGE, API de Localidades, regioes.

Code: brazilian-utils/javascript

Try it with JavaScript getRegions

Shared test cases (1) and the result in each library state.getRegions

The cases, as JSON

Get timezone

Returns the IANA time zone (tzdata zone) of a state: the zone of its capital, such as America/Sao_Paulo.

Some states straddle more than one zone, and the capital's zone says nothing about the rest. The west of Amazonas (America/Eirunepe, UTC-5) and the west of Pará (America/Santarem, UTC-3) are not represented, and Fernando de Noronha (America/Noronha, UTC-2), a district of Pernambuco, resolves as Recife (America/Recife, UTC-3).
The offsets follow the capitals: Acre UTC-5; Amazonas, Roraima, Rondônia, Mato Grosso and Mato Grosso do Sul UTC-4; the other states UTC-3. One tzdata zone can serve several states (America/Sao_Paulo also covers DF, GO, MG, ES, RJ, PR, SC and RS, and America/Fortaleza also covers MA, PI, RN and PB besides CE).
The match ignores case and surrounding whitespace.
Returns null when no state matches.

Parameter	Type	Required
`stateCode`	`string`	yes
returns	`string \| null`

Get the IANA time zone name (tzdata zone) of a Brazilian state: the zone of its capital.

Some states straddle more than one zone, and the capital's zone says nothing about the rest: the west of Amazonas (America/Eirunepe, UTC-5) and the west of Pará (America/Santarem, UTC-3) are not represented, and Fernando de Noronha (America/Noronha, UTC-2), a district of Pernambuco, resolves as Recife (UTC-3). The offsets follow the capitals: Acre UTC-5; Amazonas, Roraima, Rondônia, Mato Grosso and Mato Grosso do Sul UTC-4; the other states UTC-3.
The match ignores case and surrounding whitespace.
Returns null when no state matches.

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

getTimezoneByState('SP'); // 'America/Sao_Paulo'
getTimezoneByState('am'); // 'America/Manaus'
getTimezoneByState('AC'); // 'America/Rio_Branco'
getTimezoneByState('PE'); // 'America/Recife'
getTimezoneByState('ZZ'); // null

Source: IANA Time Zone Database, Decreto 2.784/1913, which set the legal time of Brazil, as amended by Lei 11.662/2008 and Lei 12.876/2013.

Code: brazilian-utils/javascript

Try it with JavaScript getTimezoneByState

Shared test cases (35) and the result in each library state.getTimezone

The cases, as JSON

List by region

Returns the states of a region, given its code: N, NE, SE, S or CO.

The match ignores case and surrounding whitespace: "co" and " CO " give the same list.
The states come sorted by name, as in state.list, with the same fields.
Returns an empty list for an unknown code (a region name such as Norte included) and for a value that is not a string.
Each call returns a new array of new objects.

Parameter	Type	Required
`regionCode`	`string`	yes
returns	`State[]`

Get the states of a region, given its code ('N', 'NE', 'SE', 'S' or 'CO'), sorted by name the way getStates sorts them.

The match ignores case and surrounding whitespace. Returns [] when no region matches.

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

getStatesByRegion('S').map((state) => state.code); // ['PR', 'RS', 'SC']
getStatesByRegion('co').map((state) => state.code); // ['DF', 'GO', 'MT', 'MS']
getStatesByRegion('X'); // []