USPS libera los polígonos de ZIP Code: cómo usarlos con Bun
Si alguna vez necesitaste saber "en qué ZIP Code cae este punto del mapa", ya sabes que la respuesta oficial, hasta ahora, era: no existe. El Correo de Estados Unidos (USPS) empezó a publicar en el portal PostalPro los polígonos de ZIP Code oficiales, es decir, los contornos de cada área postal (fuente). Parece una noticia de nicho. Pero mucha gente calcula envíos, impuestos, rutas y análisis de datos sobre un mapa que, hasta ayer, era un parche muy bien hecho. En este post explico qué cambió y muestro cómo convertir esos polígonos de ZIP Code en una API de búsqueda con Bun.
¿Por qué no existía un mapa oficial de ZIP Code?
Porque un ZIP Code nunca fue un área. Es una ruta de entrega. El cartero recorre una secuencia de direcciones, y ese conjunto recibe un código. No hay ninguna frontera dibujada en ningún lado. Solo una lista de calles y apartados postales.
Por eso, durante años, el mundo usó una aproximación: los ZCTAs (ZIP Code Tabulation Areas) del Census Bureau. El Censo toma los bloques censales, mira qué ZIP aparece más en cada uno y dibuja un polígono. Funciona razonablemente bien. Pero tiene tres problemas que conoce cualquiera que haya trabajado con esto:
- No son datos de la USPS, así que no coinciden al 100% con la realidad postal.
- Se actualizan al ritmo del Censo, no al ritmo de las rutas.
- Muchos ZIP de apartados postales o de edificios únicos simplemente no aparecen.
El resultado es que tienes unos 41 mil ZIP Codes en EE. UU. y un mapa "casi correcto" de ellos. "Casi correcto" está genial para un gráfico de dashboard. Para calcular el impuesto sobre ventas, es un dolor de cabeza.
Si eres de Brasil, piensa en el CEP. Es la misma lógica: un código de calle, no de área. Y la base completa de Correios, el DNE, es de pago. Ver a la USPS publicar un contorno oficial da un poco de envidia sana.
Qué publicó la USPS, en la práctica
El paquete se llama ZIP Code Boundaries (ZCB) y está en PostalPro, el portal de la USPS para quienes trabajan con correspondencia en volumen. La idea es simple: un polígono por ZIP Code, generado a partir de los datos de entrega de la propia USPS.
Antes de conectarlo a tu sistema, revisa en la página tres cosas que lo cambian todo:
- Formato del archivo. ¿Shapefile, GeoJSON, otra cosa? Eso define tu pipeline.
- Licencia y costo. "Oficial" no significa "gratis para uso comercial". Léelo antes de llevarlo a producción.
- Frecuencia de actualización. Las rutas cambian. Si el archivo es trimestral, tu caché también tiene que serlo.
No voy a inventar detalles que la página no deja claros. Lo que importa: ahora existe una fuente que respalda la propia dueña del dato.
Un ZIP Code nunca fue un lugar. Era un camino que por fin tiene contorno.
Cómo consultar polígonos de ZIP Code con Bun
El caso de uso clásico es este: llega una latitud y una longitud, y quieres devolver el ZIP. Se puede hacer sin base de datos y sin dependencias, solo con Bun. Sirve para un prototipo, para un script de enriquecimiento de datos o para un microservicio pequeño.
Si el archivo viene en shapefile, conviértelo antes. Una línea con GDAL lo resuelve:
ogr2ogr -f GeoJSON zips.geojson zcb.shp -t_srs EPSG:4326
El -t_srs EPSG:4326 garantiza que las coordenadas queden en longitud y latitud normales. Muchos bugs de "el punto cayó en el océano" son de proyección, no de código.
Ahora el servicio. Carga el GeoJSON una sola vez, calcula la caja (bounding box) de cada polígono y 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);
}
// ajusta el nombre del campo según el archivo 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;
}
// el primer anillo es el contorno, los demás son huecos
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 y lng son obligatorios" }, { status: 400 });
}
return Response.json({ zip: lookup(lng, lat) });
},
});
Ejecútalo con bun zip-lookup.ts y prueba:
curl "localhost:3000?lat=40.7484&lng=-73.9857"
Fíjate que GeoJSON usa el orden [longitude, latitude]. Todo el mundo se equivoca con esto al menos una vez. Yo me equivoqué dos.
En qué ayuda Bun aquí (y dónde se queda corto)
Bun brilla en tres puntos de este flujo:
Bun.file().json()lee y parsea un archivo grande sin ceremonia. Nada defs.readFilemásJSON.parsemás manejo de encoding.- TypeScript directo. Sin
tsc, sints-node, sin config. Escribes el.tsy lo ejecutas. Bun.servelevanta el HTTP en pocas líneas y aguanta bastantes peticiones para un servicio de este tamaño.
El filtro por bounding box es lo que lo hace rápido. En lugar de probar el punto contra 41 mil polígonos, descartas casi todos con cuatro comparaciones y solo haces el ray casting en los pocos candidatos. Para un script que enriquece una hoja de cálculo de 100 mil direcciones, esto ya alcanza de sobra.
Dónde se queda corto: memoria y escala. Un GeoJSON nacional detallado puede pesar cientos de megabytes. Cargarlo todo en la RAM de cada instancia serverless es buscar pagar caro y esperar cold starts. Y el loop lineal sobre el índice empieza a pesar si recibes miles de consultas por segundo.
Cuándo cambiar el script por PostGIS
Aquí va mi opinión fuerte: la geometría seria vive en la base de datos, no en el código de la aplicación. Si el proyecto va a producción y los datos cambian de vez en cuando, importa los polígonos en PostgreSQL con PostGIS y deja que el índice espacial haga su trabajo:
SELECT zip
FROM zip_boundaries
WHERE ST_Contains(geom, ST_SetSRID(ST_MakePoint(-73.9857, 40.7484), 4326))
LIMIT 1;
Con un índice GiST en la columna geom, esta consulta responde en milisegundos, sin importar cuántos ZIPs existan. Actualizar la base se reduce a un TRUNCATE más un import, sin redeploy. Y el servicio en Bun sigue existiendo, pero como una capa fina que recibe la petición y consulta la base.
El script en memoria todavía tiene su lugar: tests, jobs puntuales, un CLI que corre en tu portátil. Solo no dejes que se convierta en la fuente de verdad para cobrar impuestos.
Qué cambia para quien no trabaja con EE. UU.
Si tu producto no envía nada a EE. UU., el impacto directo es pequeño. El impacto indirecto es otra historia. Cuando una agencia publica el dato oficial, las librerías, los geocoders y los SaaS de direcciones empiezan a usar esa base. Los números de "qué región compra más" se vuelven más confiables. Y queda un precedente: los datos postales sí pueden convertirse en datos abiertos (o al menos accesibles).
Para mí, esta noticia va más de datos que de código. El código para consultar un polígono es el mismo desde hace décadas. Lo que faltaba era un polígono en el que se pudiera confiar. Ahora existe. Si quieres ver cómo suelo armar este tipo de servicio pequeño con Bun y Postgres, hay algunos ejemplos en mis proyectos.
Resumen para LinkedIn
El Correo de EE. UU. por fin dibujó el mapa que nunca existió. Un ZIP Code nunca fue un área. Siempre fue una ruta de entrega. Durante años, todos usaron una aproximación del Censo que era "casi correcta". Ahora la USPS publica los polígonos oficiales de cada ZIP. Para quien calcula envíos, impuestos o rutas, esto cambia las reglas del juego. Probé convertir esos polígonos en una API de búsqueda con Bun, sin base de datos y sin dependencias. Para un prototipo funciona muy bien. Pero mi opinión no cambia: la geometría seria vive en PostGIS, no en el código de la aplicación. Al final, la noticia va más de datos que de código. Escribí el paso a paso completo en el blog. El enlace está en los comentarios. #Bun #TypeScript #PostGIS #DatosAbiertos #Geolocalizacion