📍 Endereço fácil

Uma biblioteca Node.js leve, moderna e fortemente tipada para busca de endereços com fuzzy search, CEPs e cálculo de distâncias/rotas integrando múltiplos provedores (ViaCEP, Nominatim, CepAberto, OpenRouteService, etc.).

🚀 Funcionalidades

• 📮 Busca por CEP: Consulta rápida de endereços a partir do CEP.
• 📮 Busca por coordenadas: Consulta de endereços a partir de latitude, longitude.
• 🔍 Busca por Logradouro: Localize endereços mesmo digitados incorretamente informando Rua, Cidade e Estado.
• 🗺️ Geocodificação: Obtenção de coordenadas (latitude e longitude).
• 🚗 Cálculo de Distância e Tempo: Integração com OpenRouteService para matrizes de distância e tempo em rotas (a pé, moto, carro, etc.).

🚀 Instalação

npm install endereco-facil
# ou
yarn add endereco-facil

💻 Casos de uso

1. Inicializando o Cliente

import { AddressClient } from "endereco-facil";

const client = new AddressClient({
    // obrigatório para acessar as Apis
    userAgent: {appName: "MinhaAplicacao", appVersion: "1.0", email: "[email protected]",
    // se quiser limitar os provedores, inclua a prop "providers"
    providers: ["viaCep", "nominatim", "openRouteService", "cepAberto"],
    // essa prop abaixo delimita as buscas a um determinado rerângulo
    areaDeBusca: [number, number, number, number];
    // para usar os serviços do cepAberto e do openRouteService, inclua as variáveis de ambiente
    credenciais: {
        openRouteService: process.env.ORS_API_KEY, // Obtenha em https://account.heigit.org/manage/key
        cepAberto: process.env.CEP_ABERTO_TOKEN, // Obtenha em https://www.cepaberto.com/api_key
    },

});

2. Consulta por CEP

// pesquisa simples por CEP.
const resultados = await client.pesquisarPorCEP("40000-000");

3. Busca por logradouro / Fuzzy Search

// Essa função ajuda com o autocomplete, 
// é necessário bairro, cidade e estado para ajudar na pesquisa.
const resultados = await client.pesquisarPorRua({
  rua: "Avenida Jequitaia",
  bairro: "Água de Meninos",
  cidade: "Salvador",
  estado: "Bahia",
});

4. Busca por coordenadas

// Útil para pegar o endereço do usuário, sem que ele precise digitar (enviando dados de posicionamento)
// A ordem dos parâmetros deve ser [latitude, longitude]
const resultados = await client.pesquisarPorCoords([-12.981092, -38.511017])

5. Cálculo de distância / Tempo de rota

// Origem e Destino: [Latitude, Longitude]
const origem: [number, number] = [-13.0102, -38.5124];
const destino: [number, number] = [-12.9022, -38.3321];

const rotas = await client.obterDistancia(origem, destino, "driving-car");
/*
Saída do console.log(rotas):
[
  {
    distanciaEmMetros: 23450.5,
    tempoEmSegundos: 1820.3,
    distanciaFormatada: '23,45 km',
    tempoFormatado: '30 min',
    trajetoCodificado: 'fvknApc_jFa@Ig@U[UIUAM@YLe@P]VYX...'
  }
]
*/

📄 Licença

Este projeto está sob a licença MIT. Sinta-se livre para contribuir ou utilizar em seus projetos.

👤 Autor

Feito com ☕ por Anthony Victor. Entre em contato ou confira outros projetos: Se este pacote te ajudou, considere dar uma ⭐️ no repositório!