Come Aggiungere Mappe Interattive al Tuo Sito | Tutorial JavaScript

Ogni dashboard logistica, ogni annuncio immobiliare e ogni app di consegna a domicilio hanno una cosa in comune: una mappa. Se il tuo sito non ne ha ancora una, stai rinunciando a un contesto utile. È il contesto che aiuta gli utenti a capire a colpo d'occhio posizione, distanze e relazioni spaziali.

Questo tutorial ti guida nell'aggiunta di una mappa completamente interattiva a qualsiasi progetto JavaScript. Partirai da una mappa renderizzata, aggiungerai marker e popup, collegherai la ricerca degli indirizzi con la Geocoding API e finirai con un componente React pronto per la produzione, che si integra senza problemi in Next.js.

Ecco cosa avrai costruito alla fine:

• Una mappa vettoriale funzionante, autenticata con la tua chiave API
• Marker cliccabili con contenuto personalizzato nei popup
• Una funzione di ricerca degli indirizzi basata sul geocoding
• Un componente React riutilizzabile, con cleanup corretto e gestione dell'SSR di Next.js
• Una checklist di ottimizzazioni delle prestazioni per la produzione

Prerequisiti

Prima di iniziare, assicurati di avere:

• Una chiave API MapAtlas (registrati gratis, senza carta di credito). Questa unica chiave autentica tutti i servizi MapAtlas: tile, geocoding e routing.
• Un progetto JavaScript. Vanno bene HTML semplice, React, Vue o Svelte.
• Node.js 18+ se installi tramite npm.

Passo 1: installa l'SDK di MapAtlas

Aggiungi l'SDK al tuo progetto con npm:

npm install @mapmetrics/mapmetrics-gl

Se invece lavori con una semplice pagina HTML, inserisci i link CDN nel tuo <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>

Non saltare l'import del CSS. Senza di esso, i controlli della mappa e i popup vengono visualizzati senza stile. Funzionano, ma l'aspetto è rotto.

Passo 2: crea un contenitore per la mappa

L'SDK riempie l'elemento che gli indichi, quindi ti serve un <div> con un'altezza esplicita. È l'errore di configurazione più comune in assoluto: se il contenitore ha height: 0, la mappa si inizializza ma resta invisibile.

<div id="map" style="width: 100%; height: 500px;"></div>

Vanno bene sia un valore fisso in pixel sia un'unità di viewport (100vh, 50vh). Le altezze in percentuale funzionano solo se anche l'elemento padre ha un'altezza definita.

Passo 3: visualizza la tua prima mappa interattiva

Bastano tre righe di configurazione: un contenitore, un URL di stile con la tua chiave API e una posizione di partenza.

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676], // [longitudine, latitudine]
  zoom: 12,
});

Apri la pagina e vedrai una mappa vettoriale che puoi trascinare, scorrere e pizzicare per navigare. I tile vengono caricati su richiesta dai server MapAtlas, quindi non c'è un download pesante all'avvio.

Come scegliere lo stile della mappa

Gli stili della mappa si trovano nel tuo account. Nel portale MapMetrics apri Styles, crea o personalizza uno stile, salvalo e copia il suo Style URL. L'URL contiene già il tuo token, quindi va direttamente nell'opzione style. Tieni uno stile per ogni aspetto che ti serve, per esempio uno stile chiaro per le app di uso generale e uno scuro per le dashboard, e passa dall'uno all'altro con map.setStyle().

Risultato immediato: usa uno stile scuro per i pannelli di amministrazione e per gli strumenti usati in ambienti poco illuminati. Molti utenti lo preferiscono negli ambienti con poca luce, e fa risaltare sullo sfondo i layer di dati come heatmap e linee dei percorsi.

Passo 4: aggiungi marker e popup alla mappa

Una mappa senza marker è solo un'immagine di sfondo. I marker trasformano una vista statica in qualcosa con cui gli utenti possono interagire.

Un singolo marker con popup

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);

Clicca sul marker e si apre il popup. Al suo interno puoi mettere qualsiasi HTML: indirizzi, miniature, pulsanti CTA, tutto ciò che serve alla tua interfaccia.

Come visualizzare più marker a partire dai dati

La maggior parte delle app reali ha bisogno di più di un segnaposto. Un esempio concreto è OnlyHere, una guida quotidiana alle cose da fare a Londra che posiziona ogni evento su una mappa interattiva MapAtlas, così puoi scoprire cosa succede per locale e per quartiere. Scorri un array con un ciclo e crea un marker per ogni elemento:

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 sulle prestazioni: i marker HTML sono elementi del DOM, quindi qualche centinaio di marker rallenta la mappa quando è poco zoomata. A quel punto sposta i punti in una sorgente GeoJSON con clustering (supportato nativamente dall'SDK) e disegnali come layer. Consulta la documentazione dell'SDK per configurare il clustering.

Passo 5: aggiungi la ricerca degli indirizzi con la Geocoding API

La Geocoding API trasforma una query testuale (un indirizzo, il nome di una città o un punto di riferimento) in coordinate verso cui spostare la mappa, da segnare con un marker o da usare in una richiesta di routing.

async function searchAddress(query) {
  const url = new URL('https://gateway.mapmetrics-atlas.net/forward-geocode/');
  url.searchParams.set('text', query);
  url.searchParams.set('token', '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);
}

// Prova
searchAddress('Rijksmuseum, Amsterdam');

I risultati arrivano come feature GeoJSON, quindi si collegano direttamente a qualsiasi layer compatibile con GeoJSON, a una tabella dati o a una chiamata API successiva.

Crea una barra di ricerca in tempo reale in meno di 30 righe: collega searchAddress all'evento input di un campo di testo, applica un debounce di 300ms e ottieni una ricerca sulla mappa in stile autocomplete, senza dipendenze aggiuntive.

Come integrare le mappe interattive in React

Un componente mappa riutilizzabile

Inserisci l'inizializzazione della mappa in useEffect, così viene eseguita dopo il mount del DOM, e restituisci una funzione di cleanup per evitare memory leak all'unmount:

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://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=${apiKey}`,
      center,
      zoom,
    });

    return () => map.remove();
  }, [apiKey]);

  return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}

Usalo in qualsiasi punto del tuo albero di componenti:

<MapAtlasMap
  apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY}
  center={[4.9041, 52.3676]}
  zoom={13}
/>

Come gestire il rendering lato server di Next.js

L'SDK della mappa dipende da API del browser (window, document) che durante l'SSR non esistono. Importa il componente in modo dinamico, con l'SSR disattivato:

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 }} />
    ),
  }
);

Il placeholder loading mantiene stabile il layout mentre si scarica il bundle della mappa ed evita il cumulative layout shift (CLS), che conta sia per l'esperienza utente sia per i Core Web Vitals.

Checklist delle prestazioni per la produzione

Prima di andare in produzione, verifica queste ottimizzazioni:

• Carica in lazy loading le mappe sotto la piega. Usa IntersectionObserver per inizializzare la mappa solo quando il suo contenitore entra nella viewport. Così rimandi circa 250 KB di JavaScript compresso rispetto al caricamento iniziale della pagina.
• Usa i tile vettoriali. I tile vettoriali restano nitidi su qualsiasi densità di schermo, generano meno richieste mentre l'utente zooma e si possono ristilizzare lato client senza richieste aggiuntive al server. MapAtlas fornisce tile vettoriali per impostazione predefinita.
• Raggruppa i marker quando sono tanti. Qualche centinaio di marker HTML su una vista poco zoomata provoca cali di frame evidenti. Un layer GeoJSON con clustering evita il problema.
• Limita le chiavi usate nel browser. Una chiave usata nel browser, anche se sta in una variabile d'ambiente NEXT_PUBLIC_, è visibile a chiunque apra i DevTools. Non fare mai commit delle chiavi in un repository pubblico, limita le chiavi del browser ai tuoi domini nel portale e, per le operazioni sensibili, fai passare le richieste dal tuo backend tramite proxy.
• Imposta maxBounds per le app regionali. Se ai tuoi utenti interessa una sola area geografica, limita la viewport così i tile esterni a quell'area non vengono mai richiesti. Meno chiamate di rete, caricamento più rapido.

Cosa costruire dopo

Hai una mappa che si visualizza, mostra marker, cerca indirizzi e si integra con React. Ecco come proseguire:

• Routing API: richiedi indicazioni passo passo tra due coordinate. Restituisce la polilinea del percorso, la distanza totale e il tempo di percorrenza stimato.
• Isochrone API: genera un poligono che copre tutti i punti raggiungibili entro n minuti. Si usa per zone di consegna, mappe di copertura dei servizi e analisi dei bacini d'utenza.
• Matrix API: calcola tempi di percorrenza e distanze tra più origini e destinazioni con una sola richiesta. È indispensabile per il dispatch delle flotte e l'ottimizzazione logistica.

Il riferimento completo dell'SDK, la documentazione degli stili e le guide delle API sono disponibili su docs.mapatlas.xyz.

Leggi anche: Come l'AI trova il tuo sito web nel 2026, ovvero perché dati strutturati e accessibili tramite API come questi sono oggi la chiave per farsi trovare dagli agenti AI.

Domande frequenti

Posso aggiungere mappe interattive al mio sito gratis?

Sì. MapAtlas offre un piano gratuito che non richiede la carta di credito alla registrazione. Include il rendering dei tile vettoriali, la Geocoding API e la Routing API. È sufficiente per lo sviluppo e per un uso in produzione su piccola scala.

Come si inserisce una mappa in un'app React o Next.js?

Inserisci l'inizializzazione della mappa in un hook useEffect, così viene eseguita dopo il mount del DOM. In Next.js usa dynamic() con ssr: false per evitare errori di rendering lato server. Questo tutorial copre entrambi gli approcci con esempi pronti da copiare e incollare.

Cosa sono i tile vettoriali e perché preferirli ai raster?

I tile vettoriali descrivono gli elementi della mappa (strade, edifici, etichette) come geometria matematica invece che come immagini già renderizzate in pixel. Restano nitidi a qualsiasi risoluzione, richiedono meno download mentre zoomi e si possono ristilizzare completamente sul client senza ulteriori richieste al server.

Quanti marker posso aggiungere prima che le prestazioni calino?

In genere il rendering peggiora quando arrivi a qualche centinaio di marker HTML ai livelli di zoom bassi. La soluzione è il clustering: l'SDK di MapAtlas supporta nativamente il clustering delle sorgenti GeoJSON, che raggruppa i marker vicini a zoom bassi e li separa man mano che l'utente ingrandisce.

Serve esperienza GIS per usare MapAtlas?

No. L'SDK è pensato per sviluppatori web, non per specialisti GIS. Inizializzi una mappa con coordinate e livello di zoom, aggiungi marker con coppie longitudine/latitudine e chiami la Geocoding API con testo semplice. Non servono database spaziali né strumenti GIS.

Letture consigliate:

• Crea una mappa immobiliare con clustering
• Come creare uno store locator con una API di mappe
• Alternative alla Google Maps API per sviluppatori UE
• Inizia a sviluppare gratis