Todo panel de logística, listado de bienes raíces y aplicación de entrega de alimentos tiene algo en común: un mapa. Si tu sitio web aún no tiene uno, estás dejando contexto sobre la mesa. Contexto que ayuda a los usuarios a entender ubicación, proximidad y relaciones espaciales de un vistazo.
Este tutorial te guía a través de agregar un mapa completamente interactivo a cualquier proyecto JavaScript. Comenzarás con un mapa renderizado, agregarás marcadores y ventanas emergentes, conectarás la búsqueda de direcciones con la API de Geocodificación y terminarás con un componente React listo para producción que se integra perfectamente en Next.js.
Aquí está lo que construirás al final:
- Un mapa vectorial en vivo autenticado con tu clave API
- Marcadores interactivos con contenido de ventana emergente personalizado
- Una función de búsqueda de direcciones impulsada por geocodificación
- Un componente React reutilizable con limpieza adecuada y manejo de SSR de Next.js
- Una lista de control de optimizaciones de rendimiento para producción
Requisitos previos
Antes de comenzar, asegúrate de tener:
- Una clave API de MapAtlas (regístrate gratis, sin tarjeta de crédito requerida). Esta única clave autentica todos los servicios de MapAtlas: tiles, geocodificación y enrutamiento.
- Un proyecto JavaScript. HTML plano, React, Vue o Svelte funcionan todos.
- Node.js 18+ si estás instalando a través de npm.
Paso 1: Instalar el SDK de MapAtlas
Extrae el SDK a tu proyecto con npm:
npm install @mapmetrics/mapmetrics-gl
Si en cambio estás trabajando con una página HTML plana, coloca los enlaces CDN en tu <head>:
<link
rel="stylesheet"
href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css"
/>
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>
No omitas la importación de CSS. Sin ella, los controles del mapa y las ventanas emergentes se renderizan sin estilo. Funcionan, pero se ven visualmente rotos.
Paso 2: Crear un contenedor de mapa
El SDK completa cualquier elemento que señales, por lo que necesitas un <div> con una altura explícita. Este es el error de configuración más común: si el contenedor tiene height: 0, el mapa se inicializa pero permanece invisible.
<div id="map" style="width: 100%; height: 500px;"></div>
Un valor de píxel fijo o unidad de viewport (100vh, 50vh) funcionan ambos. Las alturas de porcentaje solo funcionan si el elemento padre también tiene una altura definida.
Paso 3: Renderizar tu primer mapa interactivo
Tres líneas de configuración es todo lo que necesitas: un contenedor, una URL de estilo con tu clave API y una posición inicial.
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const map = new mapmetricsgl.Map({
container: 'map',
style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
center: [4.9041, 52.3676], // [longitude, latitude]
zoom: 12,
});
Abre la página y verás un mapa vectorial que puedes arrastrar, desplazar y pellizcar para navegar. Los tiles se cargan bajo demanda desde los servidores de MapAtlas, por lo que no hay una descarga pesada inicial.
Elegir un estilo de mapa
Cambia el segmento de ruta en la URL de estilo para cambiar el aspecto por completo:
| Estilo | Ruta de URL | Mejor para |
|---|---|---|
| Basic | /styles/basic/style.json | Aplicaciones de propósito general |
| Bright | /styles/bright/style.json | Superposiciones de visualización de datos |
| Dark | /styles/dark/style.json | Paneles de control, modo nocturno, análisis |
Una ganancia rápida: Usa el estilo Dark para paneles administrativos y herramientas utilizadas en entornos con poca luz. Reduce la fatiga visual y hace que las capas de datos como mapas de calor y líneas de ruta destaquen visualmente contra el fondo.
Paso 4: Agregar marcadores y ventanas emergentes a tu mapa
Un mapa sin marcadores es solo una imagen de fondo. Los marcadores convierten una vista estática en algo con lo que los usuarios pueden interactuar.
Marcador único con una ventana emergente
const popup = new mapmetricsgl.Popup().setHTML(`
<strong>Amsterdam Central</strong>
<p>Stationsplein, 1012 AB Amsterdam</p>
`);
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat([4.9001, 52.3791])
.setPopup(popup)
.addTo(map);
Haz clic en el marcador y la ventana emergente se abre. Puedes poner cualquier HTML dentro: direcciones, miniaturas, botones de CTA, lo que tu interfaz de usuario requiera.
Trazar múltiples marcadores desde datos
La mayoría de aplicaciones del mundo real necesitan más de un marcador. Recorre un array y crea un marcador para cada entrada:
const locations = [
{ name: 'Amsterdam', coords: [4.9041, 52.3676] },
{ name: 'Rotterdam', coords: [4.4777, 51.9244] },
{ name: 'Utrecht', coords: [5.1214, 52.0907] },
];
locations.forEach(({ name, coords }) => {
const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat(coords)
.setPopup(popup)
.addTo(map);
});
Nota de rendimiento: Una vez que superas aproximadamente 100 a 200 marcadores, el renderizado se ralentiza notablemente en vistas alejadas. Habilita la agrupación de fuente GeoJSON (compatible con el SDK) para agrupar marcadores cercanos en niveles de zoom bajos. Consulta la documentación del SDK para la configuración de agrupación.
Paso 5: Agregar búsqueda de direcciones con la API de Geocodificación
La API de Geocodificación convierte una consulta de texto (una dirección postal, nombre de ciudad o punto de referencia) en coordenadas que puedes usar para desplazar, marcar o alimentar en una solicitud de enrutamiento.
async function searchAddress(query) {
const url = new URL('https://api.mapatlas.eu/geocoding/v1/search');
url.searchParams.set('text', query);
url.searchParams.set('key', 'YOUR_API_KEY');
const res = await fetch(url);
const data = await res.json();
if (!data.features.length) return;
const [lng, lat] = data.features[0].geometry.coordinates;
const label = data.features[0].properties.label;
map.flyTo({ center: [lng, lat], zoom: 14 });
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat([lng, lat])
.setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
.addTo(map);
}
// Pruébalo
searchAddress('Rijksmuseum, Amsterdam');
Los resultados regresan como características GeoJSON, por lo que se conectan directamente a cualquier capa compatible con GeoJSON, tabla de datos o llamada API descendente.
Construye una barra de búsqueda en vivo en menos de 30 líneas: Conecta
searchAddressal eventoinputde un campo de texto, aplica un debounce de 300ms, y tienes búsqueda de mapa de estilo autocompletado sin dependencias adicionales.
Integración de mapas interactivos con React
Un componente de mapa reutilizable
Envuelve la inicialización del mapa en useEffect para que se ejecute después de que el DOM se monte, y retorna una función de limpieza para evitar pérdidas de memoria al desmontar:
import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
export function MapAtlasMap({
apiKey,
center = [4.9041, 52.3676],
zoom = 12,
}) {
const containerRef = useRef(null);
useEffect(() => {
const map = new mapmetricsgl.Map({
container: containerRef.current,
style: `https://tiles.mapatlas.eu/styles/basic/style.json?key=${apiKey}`,
center,
zoom,
});
return () => map.remove();
}, [apiKey]);
return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}
Úsalo en cualquier lugar de tu árbol de componentes:
<MapAtlasMap
apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY}
center={[4.9041, 52.3676]}
zoom={13}
/>
Manejo de renderizado del lado del servidor de Next.js
El SDK del mapa depende de APIs del navegador (window, document) que no existen durante SSR. Importa el componente dinámicamente con SSR deshabilitado:
import dynamic from 'next/dynamic';
const MapAtlasMap = dynamic(
() => import('./MapAtlasMap').then(m => m.MapAtlasMap),
{
ssr: false,
loading: () => (
<div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />
),
}
);
El marcador de posición loading mantiene tu diseño estable mientras se descarga el paquete del mapa, previniendo el cambio de diseño acumulativo (CLS), lo que importa tanto para la experiencia del usuario como para Core Web Vitals.
Lista de control de rendimiento de producción
Antes de lanzar, revisa estas optimizaciones:
- Carga perezosa de mapas debajo del pliegue. Usa
IntersectionObserverpara inicializar el mapa solo cuando su contenedor se desplaza a la vista. Esto difiere aproximadamente 200 KB de JavaScript de la carga de página inicial. - Mantente con tiles vectoriales. Los tiles vectoriales se escalan limpiamente a cualquier densidad de pantalla, se cargan más rápido que las imágenes raster, y pueden ser restyled del lado del cliente sin solicitudes adicionales del servidor. MapAtlas sirve tiles vectoriales de forma predeterminada.
- Agrupa conjuntos de marcadores grandes. Más allá de 100 a 200 marcadores, el renderizado sin agrupar en una vista alejada causa caídas de fotogramas notables. La agrupación resuelve esto completamente.
- Mantén tu clave API del lado del servidor. Nunca confirmes claves en un repositorio público. Usa variables de entorno (
NEXT_PUBLIC_MAPATLAS_KEYen Next.js) o proxy de solicitudes a través de tu backend para operaciones sensibles. - Establece
maxBoundspara aplicaciones regionales. Si tus usuarios solo se preocupan por una geografía, restringe el viewport para que los tiles fuera de esa área nunca se soliciten. Menos llamadas de red, carga más rápida.
Qué construir a continuación
Tienes un mapa que renderiza, muestra marcadores, busca direcciones e integra con React. Aquí está dónde ir desde aquí:
- Routing API: Solicita direcciones paso a paso entre dos coordenadas. Devuelve una polilínea de ruta, distancia total y tiempo de viaje estimado.
- Isochrone API: Genera un polígono que cubre todos los puntos alcanzables dentro de n minutos. Se usa para zonas de entrega, mapas de cobertura de servicio y análisis de área de influencia.
- Matrix API: Calcula el tiempo de viaje y la distancia entre múltiples orígenes y destinos en una sola solicitud. Esencial para despacho de flota y optimización de logística.
La referencia completa del SDK, documentación de estilos y guías de API están disponibles en docs.mapatlas.xyz.
Preguntas frecuentes
¿Puedo agregar mapas interactivos a mi sitio web de forma gratuita?
Sí. MapAtlas ofrece un nivel gratuito sin requerir tarjeta de crédito al registrarse. Incluye renderizado de tiles vectoriales, la API de Geocodificación y la API de Enrutamiento. Eso es suficiente para desarrollo y uso en producción a pequeña escala.
¿Cómo integro un mapa en una aplicación React o Next.js?
Envuelve la inicialización del mapa en un hook useEffect para que se ejecute después de que el DOM se monte. En Next.js, usa dynamic() con ssr: false para evitar errores de renderizado del lado del servidor. Ambos enfoques se cubren con ejemplos listos para copiar y pegar en este tutorial.
¿Qué son los tiles vectoriales y por qué debería usarlos en lugar de raster?
Los tiles vectoriales describen características del mapa (carreteras, edificios, etiquetas) como geometría matemática en lugar de imágenes de píxeles prerenderizadas. Se escalan nitidamente a cualquier resolución, se descargan más rápido y pueden ser restyled completamente en el cliente sin viajes de ida y vuelta adicionales del servidor.
¿Cuántos marcadores puedo agregar antes de que el rendimiento se degradue?
El renderizado típicamente se degrada más allá de 100 a 200 marcadores en niveles de zoom bajos. La solución es la agrupación: el SDK de MapAtlas soporta la agrupación de fuente GeoJSON de forma nativa, agrupando marcadores cercanos en zoom bajo y expandiéndolos a medida que el usuario hace zoom.
¿Necesito experiencia en GIS para usar MapAtlas?
No. El SDK está diseñado para desarrolladores web, no para especialistas en GIS. Inicializas un mapa con coordenadas y nivel de zoom, agregas marcadores con pares de longitud/latitud, y llamas a la API de Geocodificación con texto plano. No se requieren bases de datos espaciales ni herramientas GIS.