CEP Distribuição Otimizador: onde instalar CD a partir de um CSV de CEP

TL;DR

• Você sobe um CSV de CEP brasileiro, com volume por pedido opcional, e a ferramenta responde em segundos em quais cidades ficam os melhores centros de distribuição — para reduzir distância e, por consequência, tempo e custo de frete.
• O geocoding de CEP para município, com latitude e longitude reais, é offline, de base embarcada, então cem mil pedidos não viram cem mil chamadas de API.
• A recomendação é uma heurística gulosa de k-median (ou p-median): escolhe as cidades que minimizam a distância total ponderada pela demanda, não as cidades com mais pedido.
• Roda local, de graça e offline, e entrega mapa PNG estático mais mapa HTML interativo.

O que é e para quem

O CEP Distribuição Otimizador é uma CLI em Node.js para a pergunta que toda operação de e-commerce faz uma vez por ano: com pedido espalhado pelo país, em quais cidades um centro de distribuição de fato reduz a distância de frete?

É para quem cuida de operação e logística, tem o CSV de pedido e a planilha, e para o analista a quem perguntaram "quantos CDs precisamos" e que prefere responder com uma curva em vez de com opinião.

O que ele faz

• Geocoding offline de CEP para município, com latitude e longitude reais, instantâneo e escalável para centenas de milhares de pedido.
• Recomenda cidades reais para CD, escolhendo as que minimizam a distância total ponderada pela demanda, com heurística gulosa de k-median ou p-median.
• Curva "quantos CDs?" mostrando o retorno decrescente de abrir um, dois, três centros e sugerindo um número razoável.
• Ponderação por volume quando o CSV tem quantidade, peso ou faturamento por linha, então a recomendação é puxada pela demanda de verdade em vez de pela contagem de CEP.
• Mapas: PNG estático com contorno real do Brasil, offline, mais HTML interativo com Leaflet e OpenStreetMap para apresentar.

A ponderação é o que muda a resposta: mil pedidos numa cidade e um pedido em outra cidade são duas linhas por contagem e nada por volume, e a ferramenta lê os dois.

Instalação e uso

Precisa de Node.js 18+, porque usa fetch nativo. O pacote canvas compila biblioteca nativa na instalação.

git clone https://github.com/artificialguybr/cep-distribuicao-otimizador.git
cd cep-distribuicao-otimizador
npm install
npm run build

# recomendar as melhores cidades para CD (número sugerido automaticamente)
node dist/cli.js centers examples/pedidos_exemplo.csv -o mapa

# forçar exatamente 3 centros e gerar os mapas
node dist/cli.js centers examples/pedidos_exemplo.csv -n 3 -o mapa

Isso gera mapa.png (estático) e mapa.html (interativo), além de imprimir a curva de retorno decrescente e a lista de cidades recomendadas.

Quando usar, quando não usar

Use quando você tem um CSV de CEP e precisa de resposta defensável sobre onde abrir CD, quando quer a pergunta "quantos" respondida com curva em vez de com meta, ou quando quer testar a premissa antes de fechar um contrato de galpão.

Não use como substituto de estudo de rede. O README descreve heurística gulosa que minimiza distância ponderada, que é uma boa primeira resposta e não um modelo de custo completo — tarifa de frete, aluguel de galpão, mão de obra e nível de serviço ficam de fora. E não use em CSV com CEP sujo: a precisão do geocoding é a entrada de tudo o que vem depois.

Sources

1. CEP Distribuição Otimizador — repositório — recursos, geocoding offline, heurística k-median, mapas, instalação e uso citados acima.
2. README.md — comandos de instalação e uso, formato do arquivo de entrada, requisitos.

Página do projeto: CEP Distribuição Otimizador

FAQ

Ele chama API de geocoding para cada CEP? Não. O geocoding de CEP para município usa base embarcada, então é offline e não depende de milhares de chamada externa.

Qual algoritmo escolhe as cidades? Heurística gulosa de k-median ou p-median que minimiza a distância total ponderada pela demanda.

Dá para forçar a quantidade de CD? Sim, com a flag -n, que força exatamente aquele número; sem ela, a ferramenta sugere um número a partir da curva de retorno decrescente.

Ele considera o volume do pedido? Sim, quando o CSV tem coluna de quantidade, peso ou faturamento, a recomendação é puxada pela demanda real em vez de pela contagem de CEP.