USPS libera polígonos de ZIP Code: como usar com Bun
Quem já precisou saber "em qual ZIP Code fica esse ponto no mapa" sabe que a resposta oficial, até agora, era: não tem. Os Correios americanos (USPS) passaram a publicar no portal PostalPro os polígonos de ZIP Code oficiais, os contornos de cada área postal (fonte). Parece notícia de nicho. Só que muita gente faz frete, imposto, roteamento e análise de dados em cima de um mapa que, até ontem, era uma gambiarra bem educada. Neste post eu explico o que mudou e mostro como transformar esses polígonos de ZIP Code numa API de busca com Bun.
Por que não existia mapa oficial de ZIP Code?
Porque ZIP Code nunca foi uma área. É uma rota de entrega. O carteiro passa por uma sequência de endereços, e esse conjunto ganha um código. Não tem fronteira desenhada em lugar nenhum, só uma lista de ruas e caixas postais.
Por isso, durante anos, o mundo usou uma aproximação: os ZCTAs (ZIP Code Tabulation Areas) do Census Bureau. O Censo pega os blocos censitários, olha qual ZIP aparece mais em cada um e desenha um polígono. Funciona razoavelmente. Mas tem três problemas que todo mundo que mexeu com isso conhece:
- Não é dado da USPS, então não bate 100% com a realidade postal.
- É atualizado no ritmo do Censo, não no ritmo das rotas.
- Muito ZIP de caixa postal ou de prédio único simplesmente não aparece.
O resultado é que você tem uns 41 mil ZIP Codes nos EUA e um mapa "quase certo" deles. "Quase certo" é ótimo para gráfico de dashboard. Para calcular imposto sobre venda, é uma dor de cabeça.
Se você é do Brasil, pensa no CEP. É a mesma lógica: código de logradouro, não de área. E a base completa dos Correios, o DNE, é paga. Ver a USPS publicar contorno oficial é um pouco de inveja saudável.
O que a USPS publicou, na prática
O pacote se chama ZIP Code Boundaries (ZCB) e fica no PostalPro, o portal da USPS voltado para quem trabalha com correspondência em volume. A ideia é simples: um polígono por ZIP Code, gerado a partir dos dados de entrega da própria USPS.
Antes de sair plugando no seu sistema, confira na página três coisas que mudam tudo:
- Formato do arquivo. Shapefile, GeoJSON, outra coisa? Isso define sua pipeline.
- Licença e custo. "Oficial" não quer dizer "grátis para uso comercial". Leia antes de colocar em produção.
- Frequência de atualização. Rota muda. Se o arquivo é trimestral, seu cache também tem que ser.
Não vou inventar detalhe que a página não deixa claro. O ponto que importa: agora existe uma fonte que a própria dona do dado assina embaixo.
ZIP Code nunca foi um lugar. Era um caminho que finalmente ganhou contorno.
Como consultar polígonos de ZIP Code com Bun
O caso de uso clássico é este: chega uma latitude e longitude e você quer devolver o ZIP. Dá para fazer isso sem banco e sem dependência, só com Bun. Serve para protótipo, para script de enriquecimento de dados ou para um microserviço pequeno.
Se o arquivo vier em shapefile, converta antes. Uma linha com GDAL resolve:
ogr2ogr -f GeoJSON zips.geojson zcb.shp -t_srs EPSG:4326
O -t_srs EPSG:4326 garante que as coordenadas fiquem em longitude e latitude normais. Muito bug de "ponto caiu no oceano" é projeção errada, não código errado.
Agora o serviço. Ele carrega o GeoJSON uma vez, calcula a caixa (bounding box) de cada polígono e responde por HTTP:
// zip-lookup.ts
type Ring = [number, number][];
type Feature = {
properties: Record<string, string>;
geometry: { type: "Polygon" | "MultiPolygon"; coordinates: any };
};
const geo = await Bun.file("zips.geojson").json();
const index = geo.features.map((f: Feature) => {
const polys: Ring[][] =
f.geometry.type === "Polygon" ? [f.geometry.coordinates] : f.geometry.coordinates;
let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
for (const [x, y] of polys.flatMap((p) => p[0])) {
minX = Math.min(minX, x); maxX = Math.max(maxX, x);
minY = Math.min(minY, y); maxY = Math.max(maxY, y);
}
// ajuste o nome do campo conforme o arquivo real
return { zip: f.properties.ZIP ?? f.properties.zip, polys, box: [minX, minY, maxX, maxY] };
});
function inRing(x: number, y: number, ring: Ring) {
let inside = false;
for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
const [xi, yi] = ring[i], [xj, yj] = ring[j];
if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
}
return inside;
}
// primeiro anel é o contorno, os outros são buracos
const inPolygon = (x: number, y: number, p: Ring[]) =>
inRing(x, y, p[0]) && !p.slice(1).some((hole) => inRing(x, y, hole));
function lookup(lng: number, lat: number) {
for (const z of index) {
const [a, b, c, d] = z.box;
if (lng < a || lng > c || lat < b || lat > d) continue;
if (z.polys.some((p: Ring[]) => inPolygon(lng, lat, p))) return z.zip;
}
return null;
}
Bun.serve({
port: 3000,
fetch(req) {
const url = new URL(req.url);
const lat = Number(url.searchParams.get("lat"));
const lng = Number(url.searchParams.get("lng"));
if (!Number.isFinite(lat) || !Number.isFinite(lng)) {
return Response.json({ error: "lat e lng são obrigatórios" }, { status: 400 });
}
return Response.json({ zip: lookup(lng, lat) });
},
});
Roda com bun zip-lookup.ts e testa:
curl "localhost:3000?lat=40.7484&lng=-73.9857"
Repare que o GeoJSON usa a ordem [longitude, latitude]. Todo mundo erra isso pelo menos uma vez. Eu errei duas.
O que o Bun ajuda aqui (e onde ele para)
O Bun brilha em três pontos nesse fluxo:
Bun.file().json()lê e faz parse de um arquivo grande sem cerimônia. Nada defs.readFilemaisJSON.parsemais tratamento de encoding.- TypeScript direto. Sem
tsc, semts-node, sem config. Você escreve o.tse roda. Bun.servesobe o HTTP em poucas linhas e aguenta bastante requisição para um serviço desse tamanho.
O filtro por bounding box é o que deixa isso rápido. Em vez de testar o ponto contra 41 mil polígonos, você descarta quase todos com quatro comparações e só faz o ray casting nos poucos candidatos. Para um script que enriquece uma planilha de 100 mil endereços, isso já resolve com folga.
Onde ele para: memória e escala. Um GeoJSON nacional detalhado pode ter centenas de megabytes. Carregar tudo na RAM de cada instância serverless é pedir para pagar caro e esperar cold start. E o loop linear sobre o índice começa a pesar se você recebe milhares de consultas por segundo.
Quando trocar o script por PostGIS
Aqui vai minha opinião forte: geometria séria mora no banco, não no código da aplicação. Se o projeto vai para produção e o dado muda de tempos em tempos, importe os polígonos no PostgreSQL com PostGIS e deixe o índice espacial trabalhar:
SELECT zip
FROM zip_boundaries
WHERE ST_Contains(geom, ST_SetSRID(ST_MakePoint(-73.9857, 40.7484), 4326))
LIMIT 1;
Com um índice GiST na coluna geom, essa consulta responde em milissegundos, independente de quantos ZIPs existem. Atualizar a base vira um TRUNCATE mais um import, sem redeploy. E o serviço em Bun continua existindo, só que como uma camada fina que recebe a requisição e consulta o banco.
O script em memória ainda tem lugar: testes, jobs pontuais, um CLI que roda no seu notebook. Só não deixe ele virar a fonte de verdade de cobrança de imposto.
O que isso muda para quem não trabalha com os EUA
Se o seu produto não envia nada para os EUA, o impacto direto é pequeno. O impacto indireto é outro. Quando uma agência publica o dado oficial, as bibliotecas, os geocoders e os SaaS de endereço passam a usar essa base. Os números de "qual região compra mais" ficam mais confiáveis. E fica um precedente: dado postal pode, sim, virar dado aberto (ou pelo menos acessível).
Na minha visão, essa notícia é mais sobre dados do que sobre código. O código para consultar um polígono é o mesmo há décadas. O que faltava era um polígono em que dava para confiar. Agora tem. Se você quer ver como eu costumo montar esse tipo de serviço pequeno com Bun e Postgres, tem alguns exemplos nos meus projetos.
Resumo para o LinkedIn
Os Correios dos EUA finalmente desenharam o mapa que nunca existiu. ZIP Code nunca foi uma área, sempre foi uma rota de entrega. Por anos, todo mundo usou uma aproximação do Censo que era "quase certa". Agora a USPS publica os polígonos oficiais de cada ZIP. Pra quem calcula frete, imposto ou roteamento, isso muda o jogo. Testei transformar esses polígonos numa API de busca com Bun, sem banco e sem dependência. Funciona muito bem pra protótipo. Mas a minha opinião continua: geometria séria mora no PostGIS, não no código da aplicação. No fim, a notícia é mais sobre dados do que sobre código. Escrevi o passo a passo completo no blog, o link está nos comentários. #Bun #TypeScript #PostGIS #DadosAbertos #Geolocalizacao