Offline

A synchronous, zero-network API powered by the official Correios CEP allocation map bundled with the library (~2 KB). Importable standalone:

import {
  resolveCepOffline,
  stateFromCep,
  isCepAllocated,
  cepMatchesState,
  toPartialAddress,
} from "@eusilvio/cep-lookup/offline";

Also re-exported from the main entry point (@eusilvio/cep-lookup) if you already use the engine.

OfflineCepInfo

interface OfflineCepInfo {
  cep: string;        // cleaned, 8 digits
  state: string;      // two-letter state abbreviation, e.g. "SP"
  stateName: string;  // e.g. "São Paulo"
  region: Region;     // e.g. "Sudeste"
  capital: string;    // state capital
  ddd: string;        // capital's area code (state-level, not street-accurate)
  ibgeState: string;  // two-digit IBGE state code
}

resolveCepOffline

resolveCepOffline(cep: string): OfflineCepInfo | null

resolveCepOffline("01310-100");
// { cep: '01310100', state: 'SP', stateName: 'São Paulo', region: 'Sudeste',
//   capital: 'São Paulo', ddd: '11', ibgeState: '35' }

Returns null when the CEP is well-formed but falls outside every allocated range. Throws CepValidationError on an invalid format.

stateFromCep

stateFromCep(cep: string): string | null

Shortcut for the state abbreviation:

stateFromCep("01310-100"); // "SP"
stateFromCep("00500-000"); // null

isCepAllocated

isCepAllocated(cep: string): boolean

Tells whether the CEP falls inside any Correios-allocated range. It rules out the impossible - it doesn't confirm the real.

isCepAllocated("01310100"); // true
isCepAllocated("00500000"); // false → no provider would ever resolve it

cepMatchesState

cepMatchesState(cep: string, state: string): boolean

0ms CEP↔state cross-field validation - catches the classic checkout typo before any request:

cepMatchesState("01310-100", "SP"); // true
cepMatchesState("01310-100", "RJ"); // false

toPartialAddress

toPartialAddress(info: OfflineCepInfo): Address

Converts an OfflineCepInfo into the partial Address that offlineFallback returns:

const info = resolveCepOffline("01310-100")!;
toPartialAddress(info);
// { cep: '01310100', state: 'SP', ddd: '11',
//   city: '', neighborhood: '', street: '', service: 'offline', partial: true }

Raw data

import { cepRanges, stateInfoByUf } from "@eusilvio/cep-lookup/offline";
import type { Region, StateInfo } from "@eusilvio/cep-lookup/offline";

cepRanges is the sorted list of [start, end, uf] ranges - lookups are binary searches. stateInfoByUf maps each state abbreviation to its name, region, capital and IBGE code.

Limits

The map covers per-state allocation, not a street database. It doesn't know city, neighborhood or street, and a CEP inside an allocated range may still not exist.