Si has escrito código que habla con una librería de mapas, has escrito código que toca el viewport. El viewport es el estado de tiempo de ejecución del mapa: dónde está centrado, qué tan ampliado está, hacia dónde apunta y, opcionalmente, cuánto está inclinado. Cada pan, zoom, rotación y clic depende de él.
Esta guía explica qué es un viewport, los cuatro valores principales que lo describen, cómo interactúa con las teselas y los bounding boxes, y los patrones de producción para guardar, restaurar y compartir el estado del viewport.
Los cuatro valores principales
Un viewport de mapa web moderno se describe con hasta cuatro valores:
- Center (
{ lat, lng }): la coordenada geográfica en el centro de la pantalla. - Zoom (un número, a menudo un float): qué tan ampliado está el mapa. Los números más altos muestran áreas más pequeñas con más detalle.
- Bearing (un número en grados, por defecto 0): la rotación del mapa desde "norte arriba". 90 significa que el este está arriba.
- Pitch (un número en grados, de 0 a ~85): la inclinación 3D. 0 es plano desde arriba, 60 es una vista en perspectiva pronunciada.
Todas las librerías de mapas modernas (MapLibre GL, Mapbox GL, OpenLayers, Leaflet, MapAtlas Dynamic Maps) exponen estos valores como estado legible y escribible. Una librería solo en 2D como Leaflet puede no exponer bearing o pitch.
Los niveles de zoom en detalle
El nivel de zoom es el más consultado de los cuatro. Es un número entero (o con decimales) que mapea el mundo en una pirámide de teselas:
- Zoom 0: mundo entero en una tesela de 256x256
- Zoom 1: mundo dividido en 4 teselas
- Zoom 2: 16 teselas
- ...
- Zoom 14: ~268 millones de teselas, escala de barrio
- Zoom 18: escala de edificio
- Zoom 22+: normalmente renderizado con escalado de estilo vectorial en lugar de datos de teselas frescos
Una regla práctica en el ecuador: cada aumento de nivel de zoom reduce a la mitad el ancho visible en pantalla. En el zoom 14, una pantalla típica muestra unas pocas manzanas. En el zoom 10, una área metropolitana. En el zoom 6, un país. La resolución efectiva depende del tamaño de la pantalla y de la proyección (Web Mercator distorsiona el norte-sur al acercarse a los polos).
La mayoría del código de producción almacena el zoom como float (por ejemplo, 14.5) porque las animaciones de zoom suave interpolan entre zooms enteros. Las peticiones de teselas ocurren en el nivel entero redondeado hacia abajo o hacia arriba, dependiendo de la convención de la librería.
Viewport vs bounding box
Un viewport es el estado de la cámara. Un bounding box es el rectángulo geográfico visible actualmente. Calculas el bbox a partir del viewport cada vez que necesitas preguntar al servidor "¿qué debería mostrar dentro de esta vista?".
En código:
const bbox = map.getBounds(); // returns { _sw: {lat, lng}, _ne: {lat, lng} }
const params = new URLSearchParams({
bbox: `${bbox._sw.lng},${bbox._sw.lat},${bbox._ne.lng},${bbox._ne.lat}`,
});
const features = await fetch(`/api/places?${params}`).then(r => r.json());
Este patrón (calcular bbox a partir del viewport, enviar al servidor, renderizar las features devueltas) es el latido de cada experiencia de búsqueda basada en viewport: inmobiliaria, listados, localizadores de tiendas, seguimiento de flotas, ride-share.
Cómo el viewport impulsa la carga de teselas
Cuando el viewport cambia, la librería de mapas determina qué teselas cubren la nueva área visible al nivel de zoom actual, descarga las que faltan del servidor (o de su caché en memoria) y las renderiza. Las teselas ya cacheadas se reutilizan; las que están fuera del viewport se conservan por si el usuario vuelve a ellas.
Un pan y zoom suave parece continuo porque la librería hace este trabajo de forma asíncrona: dibuja lo que tiene, descarga lo que necesita y actualiza el canvas a medida que llegan nuevas teselas. Los pipelines de vector tiles hacen trabajo extra para renderizar la geometría en píxeles en la GPU, que es por lo que los mapas web modernos se mantienen nítidos a cualquier zoom y rotación.
Guardar y compartir el estado del viewport
Guardar el viewport en la URL es el patrón estándar para los enlaces de mapa compartibles. La mayoría de los productos usan un hash de URL como #map=14.5/52.5200/13.4050 (zoom, lat, lng). Al cargar la página, parseas el hash y aplicas el viewport. Al cambiar el viewport, debounces unos cientos de milisegundos y actualizas el hash para que el botón atrás del navegador siga siendo útil.
Para el estado interno del navegador entre pestañas o sesiones, una clave de localStorage con la misma forma funciona. Para páginas renderizadas en el servidor, el viewport aparece frecuentemente como parámetros de query para URLs amigables con el SEO (?zoom=14&lat=52.52&lng=13.405).
Sesgo de viewport para búsqueda y autocompletado
Las APIs de geocoding aceptan el viewport (o su bbox) como parámetro de sesgo. MapAtlas expone boundary.rect.* para un filtro duro y focus.point.* para un sesgo suave. Sin sesgo, el autocompletado para "Springfield" devuelve el Springfield más popular globalmente. Con un sesgo de viewport, el usuario que escribe dentro de su mapa de Massachusetts obtiene primero los resultados de Massachusetts.
Aplica este sesgo en cada pulsación de tecla. El coste es un parámetro y unas sugerencias significativamente más relevantes.
Viewport inicial: por dónde empezar
Lo primero que toda app de mapas tiene que decidir es dónde empezar. Patrones habituales:
- Predeterminar al locale del usuario: un usuario en Alemania llega a un viewport sobre Berlín, un usuario en Francia sobre París.
- Predeterminar al último viewport del usuario: persiste el viewport entre sesiones.
- Predeterminar a los datos: si tu mapa muestra resultados de búsqueda, ajusta el bbox de esos resultados en el renderizado inicial.
- Predeterminar a la geolocalización IP del usuario: baja precisión, sin necesidad de permisos, buen fallback.
- Pedir la geolocalización del navegador solo cuando el usuario lo active explícitamente: nunca en la primera carga sin consentimiento en la UI.
Elegir un viewport inicial sensato es un detalle pequeño con un gran efecto en la calidad percibida.
Cómo MapAtlas expone el estado del viewport
El componente Dynamic Maps de MapAtlas expone las mismas APIs getCenter, getZoom, getBearing, getPitch y setView que ofrece cualquier mapa web de calidad para desarrolladores, con la adición de alojamiento exclusivo en la UE y parámetros de sesgo de viewport consistentes en los endpoints de Geocoding y Search. Para profundizar en cómo el viewport interactúa con las teselas y las proyecciones, consulta Qué es un vector tile y Qué es Web Mercator.
Preguntas frecuentes
¿Qué es un viewport de mapa?
Un viewport de mapa es la ventana visible de un mapa: el área geográfica que se muestra actualmente en pantalla, descrita por una coordenada central (latitud y longitud), un nivel de zoom (qué tan acercada o alejada está la vista), y opcionalmente un bearing (rotación) y un pitch (inclinación 3D). Todos los mapas web modernos (Google Maps, MapLibre, Mapbox GL, MapAtlas) exponen el viewport como estado que puedes leer y establecer programáticamente. El viewport cambia cada vez que el usuario hace pan, zoom, rotación o inclinación del mapa.
¿Qué es un nivel de zoom?
El nivel de zoom es un número entero (o con decimales) que controla cuánto del mundo es visible en una tesela de tamaño fijo. El zoom 0 encaja el mundo entero en una sola tesela de 256x256. Cada nivel de zoom posterior dobla la resolución: el zoom 1 tiene 4 teselas, el zoom 2 tiene 16, y así sucesivamente. El zoom 14 está a escala de barrio, el zoom 18 a escala de edificio. La mayoría de los mapas en producción admiten niveles de zoom de 0 a 22 o más, aunque las teselas subyacentes solo existen hasta un zoom determinado y se sobremuestrean a partir de ese punto.
¿Cuál es la diferencia entre un viewport y un bounding box?
Un viewport es el estado de la cámara (centro, zoom, bearing, pitch). Un bounding box es el rectángulo geográfico que la cámara muestra actualmente. Calculas el bbox a partir del viewport: dado un centro, un zoom y el tamaño de la pantalla, la librería de mapas calcula qué rectángulo lat/lng es visible. El bbox es lo que pasas a la API de geocoding como sesgo de viewport, lo que consultas en la base de datos para las features visibles y lo que registras cuando quieres saber qué estaba mirando el usuario.
¿Cómo guardo y restauro un viewport de mapa?
Serializa los cuatro valores básicos (latitud del centro, longitud del centro, zoom, bearing si admites rotación) en la URL o en el localStorage. Un patrón habitual es un hash como #map=14.5/52.5200/13.4050 para el zoom 14.5 en el centro de Berlín. Al cargar la página, parsea el hash y llama a map.setView(...) o map.flyTo(...). MapAtlas, MapLibre y Mapbox GL exponen una API getCenter / getZoom / getBearing y un equivalente a setView, por lo que este round-trip es una función helper en cualquier código de producción.
