Voltar para o blog
BunGeolocalizaçãoOpen DataTypeScript

USPS libera polígonos de ZIP Code: como usar com Bun

11 de novembro de 2026·7 min de leitura·Diego Horvatti

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:

  1. Formato do arquivo. Shapefile, GeoJSON, outra coisa? Isso define sua pipeline.
  2. Licença e custo. "Oficial" não quer dizer "grátis para uso comercial". Leia antes de colocar em produção.
  3. 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 de fs.readFile mais JSON.parse mais tratamento de encoding.
  • TypeScript direto. Sem tsc, sem ts-node, sem config. Você escreve o .ts e roda.
  • Bun.serve sobe 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