CEP

Check if a CEP (brazilian postal code) is valid.

• Accepts a string or a number. A CEP that starts with 0 has to be a string, since a number cannot keep the leading zero, and a number is only read when it is a non-negative safe integer.
• Spaces, dots, hyphens and slashes are ignored. Any other character makes the value invalid.
• getAddressInfoByCep and formatCep with pad: true are more lenient with numbers: they left-pad a number to 8 digits (1310100 is 01310-100), while isValidCep and getStateByCep read 1310100 as 7 digits and reject it.

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

isValidCep('01310100'); // true
isValidCep('92500-000'); // true (hyphen between groups)
isValidCep('92.500-000'); // true (dot and hyphen)
isValidCep('013 10 100'); // true (spaces anywhere between the digits)
isValidCep(20040020); // true (number input)
isValidCep(-20040020); // false (not a non-negative safe integer)
isValidCep('9250000A'); // false (letters are rejected)
isValidCep('12345'); // false (invalid length)

Format a CEP (brazilian postal code).

• Options (FormatCepOptions): pad left-pads the value with zeros to 8 digits before masking (default false). An empty value, or one without digits, gives '' even with pad.
• A CEP that starts with 0 given as a number loses that zero: pass a string or use pad. A number is only read when it is a non-negative safe integer; any other number returns ''.

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

formatCep('92500000'); // 92500-000
formatCep('9250000', { pad: true }); // 09250-000
formatCep(-92500000); // '' (not a non-negative safe integer)

Remove CEP formatting, keep only digits, and cap the result to 8 digits.

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

parseCep('92500-000'); // 92500000

Generate a random CEP. A CEP has no check digit, so the CEP is drawn inside the ranges the Correios assign to the states, each CEP with the same chance. It always belongs to a state, so getStateByCep never answers null for it; 00000-000 to 00999-999 and 78900-000 to 78999-999, which no state owns, are never generated. A range is the block a state owns, not a promise that every CEP in it is in use, so the CEP may not be the CEP of a real address.

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

generateCep(); // '92500000'

Fetch the address of a CEP from several providers at once and resolve to the first successful answer. The result is an AddressInfo: cep, state, city, neighborhood and street.

• Options (GetAddressInfoByCepOptions):
  • providers (CepProvider[]) lists the providers to race (default ['viacep', 'brasilapi']). 'widenet' is deprecated, left out of the default list and usually unavailable: its endpoint now redirects to ws.apicep.com, which answered 502 when last checked, so it only adds a failing provider to the race.
  • timeoutMs (number) bounds the whole lookup, retries included (default: no limit). When it runs out, every request is aborted and the call rejects with GetAddressInfoByCepServiceError.
  • signal (AbortSignal) cancels the lookup; the call rejects with signal.reason, the same as fetch.
• Accepts a string or a number. A string has any non-digit characters stripped ('CEP 01310-100' is 01310100) and has to leave 8 digits. A number is left-padded with zeros to 8 digits, since it cannot carry the leading zero of a São Paulo CEP, but only from 1000000 (01000-000, the lowest CEP the Correios assign) up. A smaller, negative or fractional number is rejected with GetAddressInfoByCepValidationError before any request is made.
• Retries transient network failures per provider.
• Rejects with GetAddressInfoByCepValidationError when the CEP is invalid, providers names no known provider or timeoutMs is not a positive finite number, with GetAddressInfoByCepNotFoundError when every provider failed and at least one reported the CEP as unknown, and with GetAddressInfoByCepServiceError when every provider failed for another reason.
• BrasilAPI answers 404 both for an unknown CEP and when the services behind it are down, so its 404 only counts as "unknown CEP" when no other provider failed to answer.
• An address is only accepted when it agrees with the CEP asked for: its digits, left-padded with zeros to 8 (a provider that answers 1310100 for 01310-100 means the same CEP), must be the CEP, and its state, when it names one, must be the state that owns the CEP range (see getStateByCep). Otherwise that provider counts as not knowing the CEP. BrasilAPI, for instance, answered 99999-999, a Rio Grande do Sul CEP, with a city of Paraná.
• Once the lookup settles, the requests of the providers that lost the race are aborted.
• All three extend GetAddressInfoByCepError, so one catch covers them.

import { getAddressInfoByCep, GetAddressInfoByCepNotFoundError } from '@brazilian-utils/brazilian-utils';

// Using the default providers (['viacep', 'brasilapi'])
const address = await getAddressInfoByCep('01310100');
// { cep: '01310100', state: 'SP', city: 'São Paulo', neighborhood: 'Bela Vista', street: 'Avenida Paulista' }

// Using a specific provider, and telling an unknown CEP from a failure
try {
  await getAddressInfoByCep('01310-100', { providers: ['brasilapi'] });
} catch (error) {
  if (error instanceof GetAddressInfoByCepNotFoundError) {
    // no provider knows the CEP
  }
}

// Using number input (will be padded automatically)
const addressFromNumber = await getAddressInfoByCep(1310100);

// Giving up after 5 seconds
const addressWithinFiveSeconds = await getAddressInfoByCep('01310100', { timeoutMs: 5000 });

Fetch the CEPs of an address from ViaCEP. Resolves to an array of CepAddressInfo.

• The argument (GetCepInfoByAddressParams) carries federalUnit, city and street. federalUnit may be lowercase; city and street are trimmed and stripped of accents before the query, and each must be a string of at least 3 characters after that, the minimum ViaCEP accepts.
• Rejects with GetCepInfoByAddressValidationError when the UF, city or street is missing or invalid (a blank value, a value that is not a string, or a city or street under 3 characters, all rejected before any request), with GetCepInfoByAddressNotFoundError when no address matches, and with GetCepInfoByAddressError when ViaCEP answers with an HTTP error status.
• Retries transient network failures, as getAddressInfoByCep does.
• Each item carries the ViaCEP payload unchanged, under ViaCEP's own field names.
• ViaCEP caps the list at 50 addresses, so a short street name that matches more streets returns only the first 50.

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

const ceps = await getCepInfoByAddress({
  federalUnit: 'MG',
  city: 'Ouro Preto',
  street: 'Rua Direita'
});

// [
//   {
//     cep: '35411-152',
//     logradouro: 'Rua Direita',
//     complemento: '',
//     unidade: '',
//     bairro: 'Riacho (Amarantina)',
//     localidade: 'Ouro Preto',
//     uf: 'MG',
//     estado: 'Minas Gerais',
//     regiao: 'Sudeste',
//     ibge: '3146107',
//     gia: '',
//     ddd: '31',
//     siafi: '4921'
//   }
// ]

Get the Brazilian state a CEP belongs to, from the CEP ranges the Correios assign to each state (the "Faixa de CEP" of each UF).

• It runs offline: no CEP API is called, so the answer says which state owns the range, not whether the CEP is in use.
• Accepts what isValidCep accepts: 8 digits, as a string or a number, with spaces, dots, hyphens and slashes ignored. A CEP that starts with 0 has to be a string, and a negative or fractional number is rejected. getAddressInfoByCep and formatCep with pad: true left-pad numbers instead (1310100 is 01310-100).
• Amazonas, Distrito Federal and Goiás have two ranges each, and no state range covers 00000-000 to 00999-999 nor 78900-000 to 78999-999.
• A range is the block the state owns, not a promise that every CEP in it is in use: 10000-000 sits unused inside the São Paulo range and still answers São Paulo.
• Returns null for an invalid CEP or one outside every range. Exports the State type.

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

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

getStateByCep(20040020);
// { code: 'RJ', name: 'Rio de Janeiro', regionCode: 'SE', regionName: 'Sudeste', ibgeCode: 33 }

getStateByCep('69300-000')?.code; // 'RR'
getStateByCep('72800-000')?.code; // 'GO'
getStateByCep('00999-999'); // null
getStateByCep('12345'); // null

Source: Correios, Busca Faixa de CEP