CEP distribution optimizer: where to put your warehouses, from a CSV of ZIP codes

TL;DR

• You upload a CSV of Brazilian ZIP codes, optionally with per-order volume, and the tool answers in seconds which cities are the best ones for distribution centres — to reduce distance, and therefore time and freight cost.
• Geocoding from CEP to municipality with real latitude and longitude is offline, from an embedded base, so a hundred thousand orders do not mean a hundred thousand API calls.
• The recommendation is a greedy k-median heuristic: pick the cities that minimize the demand-weighted total distance, not the cities with most orders.
• It runs locally, for free and offline, and produces a static PNG map plus an interactive HTML map.

What it is and who it is for

CEP Distribuição Otimizador is a Node.js CLI for the question every e-commerce operation asks once a year: with orders spread across the country, in which cities does a warehouse actually reduce shipping distance?

It is for the operations and logistics person who has the order CSV and the spreadsheet, and for the analyst who has been asked "how many distribution centres do we need" and would rather answer with a curve than with an opinion.

What it does

• Offline geocoding from CEP to municipality, with real latitude and longitude, instant and scalable to hundreds of thousands of orders.
• Recommends real cities for distribution centres, choosing the ones that minimize total distance weighted by demand, using a greedy k-median or p-median heuristic.
• A "how many centres?" curve showing the diminishing return of opening one, two, three centres, and suggesting a reasonable number.
• Volume weighting when the CSV has quantity, weight or revenue per line, so the recommendation is driven by real demand rather than by the count of ZIP codes.
• Maps: a static PNG with real Brazilian outlines, offline, plus an interactive HTML map through Leaflet and OpenStreetMap for presenting.

The weighting option is the one that changes the answer: a thousand orders in one city and one order in another city are two rows by count and nothing by volume, and the tool can read both.

Install and use

Requires Node.js 18+ because it uses native fetch. The canvas package compiles native libraries during install.

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

# recommend the best cities for distribution centres, with the number suggested automatically
node dist/cli.js centers examples/pedidos_exemplo.csv -o mapa

# force exactly three centres and generate the maps
node dist/cli.js centers examples/pedidos_exemplo.csv -n 3 -o mapa

That writes mapa.png as a static image and mapa.html as an interactive map, and prints the diminishing-returns curve plus the recommended city list.

When to use it, when not to

Use it when you have a CSV of ZIP codes and need a defensible answer about where to open a distribution centre, when you want the "how many" question answered with a curve instead of a target, or when you want to test an assumption before committing to a city.

Do not use it as a substitute for a real network-design study. The README describes a greedy heuristic that minimizes weighted distance, which is a good first answer and not a full cost model — freight rates, warehouse rent, labour and service-level targets stay outside. Do not use it on a CSV whose ZIP codes are dirty either: geocoding accuracy is the input to everything downstream.

Sources

1. CEP Distribuição Otimizador — repository — features, offline geocoding, greedy k-median heuristic, maps, install and usage quoted above.
2. README.md — install commands, usage, input file format, requirements.

Project page: CEP distribution optimizer

FAQ

Does it call a geocoding API for every ZIP code? No. Geocoding from CEP to municipality uses an embedded base, so it is offline and does not depend on thousands of external API calls.

Which algorithm picks the cities? A greedy k-median or p-median heuristic that minimizes total demand-weighted distance.

Can I force a number of centres? Yes, with the -n flag, which forces exactly that number; without it the tool suggests a number from the diminishing-returns curve.

Does it account for order volume? Yes, when the CSV has a quantity, weight or revenue column, the recommendation is pulled by real demand instead of by the count of ZIP codes.