🗺️ Brasil CEPs Offline

Inteligência geográfica e busca de CEPs 100% offline e ultrarrápida.

Esqueça limites de requisição (Rate Limits) ou latência de rede. Esta biblioteca traz um banco de dados local, entregando endereços, coordenadas e dados fiscais em milissegundos.

✨ Diferenciais

• ⚡ Performance Extrema: Consultas locais em SQLite (~1ms).
• 📍 Busca Semântica: Encontre CEPs por pedaços do nome da rua ou logradouro.
• 📦 Sync Inteligente: O banco de ~175MB é baixado automaticamente de nossa infraestrutura dedicada.

📥 Instalação e Ativação

npm install brasil-ceps-offline

# Baixa o banco de dados mais recente
npx brasil-ceps-offline sync

Recomendação: Adicione o sync no postinstall do seu package.json para garantir que o servidor sempre inicie com o banco atualizado.

💻 Como Usar

1. Busca Direta por CEP

import { findByCep } from 'brasil-ceps-offline';

const endereco = findByCep('01001-000');
// Retorna objeto Address completo ou null

2. Busca por Nome de Rua (Logradouro)

Ideal para autocompletar endereços ou encontrar CEPs sem o número em mãos.

import { findByAddress } from 'brasil-ceps-offline';

const resultados = findByAddress({
  street: 'Paulista',
  state: 'SP',  // Opcional — restringe ao estado
  limit: 5,     // Opcional — padrão: 10
});

📦 Estrutura de Resposta

{
  "cep": "01311200",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Bela Vista",
  "street": "Avenida Paulista",
  "ibge": 3550308,
  "ddd": "11",
  "timezone": "America/Sao_Paulo",
  "latitude": -23.5614,
  "longitude": -46.6558
}

🛠️ API Completa

findByCep(cep)

Busca um endereço pelo CEP. Aceita qualquer formato ("01001000", "01001-000").

const address = findByCep('74740-300');
// Address | null

findByAddress(params)

Busca endereços por trecho do logradouro. Suporta filtro por estado e limite de resultados.

const results = findByAddress({ street: 'XV de Novembro', state: 'PR', limit: 10 });
// Address[]

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|----------|-------------|---------------------------------------| | street | string | Sim | Trecho do logradouro | | state | string | Não | Sigla do estado (ex: "SP") | | limit | number | Não | Máximo de resultados (padrão: 10) |

🛡️ Tipagem (TypeScript)

A biblioteca exporta todas as interfaces para facilitar a tipagem:

import type { Address, FindByAddressParams, BrasilCepsConfig } from 'brasil-ceps-offline';

⚖️ Licença e Fonte dos Dados

Código fonte: MIT License

Dados: Baseados no Cadastro Nacional de Endereços do Censo 2022 (IBGE). Dados públicos de uso livre.