Come costruire uno store locator con una API di mappe

Uno store locator è quella piccola funzione di cui ogni attività con più punti vendita finisce per avere bisogno: il box di ricerca negozi che trasforma un CAP in un elenco breve e ordinato di punti vendita su una mappa. Vista da fuori sembra banale, e l'happy path è davvero semplice, ma uno store locator fatto bene svolge in silenzio tre compiti: capisce input di posizione imprecisi, ordina i punti vendita per prossimità reale e renderizza il risultato su una mappa con cui una persona può fare qualcosa.

Questa guida spiega come funziona davvero uno store locator, quali sono i quattro passaggi per costruirne uno con una API di mappe e quali dettagli separano una demo da qualcosa che manderesti in produzione. Ogni mappa di questo articolo è renderizzata con la API MapAtlas stessa.

Cosa fa davvero uno store locator

Togli lo styling e uno store locator è una pipeline in tre stadi:

1. Geocodifica dell'input del visitatore. «1012 Amsterdam», «SW1A 1AA» o una posizione GPS condivisa devono tutte diventare un'unica latitudine e longitudine.
2. Ranking di prossimità dei negozi. Data quella coordinata e il tuo elenco di punti vendita, individua i più vicini entro un raggio sensato.
3. Rendering dei risultati. Metti i negozi ordinati sulla mappa come marker, ciascuno con indirizzo, orari di apertura e link al percorso.

La mappa qui sotto è esattamente quel terzo stadio, renderizzata con le tile di MapAtlas: sei punti vendita nel centro di Amsterdam, segnati per distanza dal visitatore. Qui sono supermercati, ma la mappa è identica sia che i marker arrivino da un dataset di POI sia dal tuo elenco di negozi.

L'ordine dei colori è il ranking. Il visitatore ha cercato dal centro della mappa, e i marker sono i punti vendita più vicini in ordine, il più vicino per primo.

Passo 1: geocodificare l'input del visitatore

Il visitatore digita un CAP, una città o un indirizzo completo, e a te serve una coordinata. Questo è il forward geocoding.

// Turn what the visitor types into a coordinate (autocomplete geocoding)
const res = await fetch(
  `https://gateway.mapmetrics-atlas.net/autocomplete/` +
  `?token=${API_TOKEN}&text=${encodeURIComponent(query)}` +
  `&focus.point.lat=52.37&focus.point.lon=4.89` // bias toward your service area
);
const { features } = await res.json();
const [lon, lat] = features[0].geometry.coordinates; // [lon, lat]
const label = features[0].properties.label;          // "Damrak, Amsterdam, North Holland, Netherlands"

Qui contano due dettagli. Passa un focus.point vicino alla tua area di servizio così che «Cambridge» risolva su quella giusta, e gestisci il caso in cui il visitatore condivide il GPS del dispositivo invece di digitare: in quel caso hai già la coordinata e salti del tutto questo passaggio.

Passo 2: ordinare i negozi per distanza

Ora hai la coordinata del visitatore. I negozi, invece, sono dati tuoi: un elenco di punti vendita, ciascuno con latitudine e longitudine, che vive nel tuo database. Ordinarli è un calcolo di distanza in linea d'aria (haversine), senza alcuna chiamata API:

// Your branches, each with a lat/lon. Rank by distance from the visitor.
const ranked = stores
  .map(s => ({ ...s, distance_m: haversine(lat, lon, s.lat, s.lon) }))
  .sort((a, b) => a.distance_m - b.distance_m)
  .slice(0, 6);

Questo è tutto ciò che serve a uno store locator di base. Per una rete estesa filtreresti prima su una bounding box attorno al visitatore, così da non misurare la distanza da ogni punto vendita a ogni request, per poi ordinare i sopravvissuti. L'output è un elenco breve dei punti vendita più vicini, ciascuno con il suo distance_m.

Passo 3: ordinare per distanza, poi affinare per tempo di percorrenza

La distanza in linea d'aria è il default giusto. È veloce, non richiede chiamate extra e per una rete densa è di solito corretta. Ma il negozio più vicino in linea d'aria non è sempre il più rapido da raggiungere: un punto vendita a 400 metri dall'altra parte di un fiume può significare una deviazione di dieci minuti fino al ponte più vicino.

Per uno store locator in cui «più vicino» significhi davvero «più rapido da raggiungere», riordina i pochi migliori candidati in base al tempo di percorrenza reale con una chiamata directions o matrix:

// Re-rank the closest stores by real drive time (MapAtlas Matrix API)
const res = await fetch(`https://gateway.mapmetrics-atlas.net/matrix/?token=${API_TOKEN}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sources: [{ lat, lon }],
    targets: top3.map(s => ({ lat: s.lat, lon: s.lon })),
    costing: 'auto', // 'auto' | 'bicycle' | 'pedestrian'
  }),
});
const { sources_to_targets } = await res.json();
const row = sources_to_targets[0]; // one entry per target, each with .time (seconds)
const byTime = top3
  .map((s, i) => ({ ...s, time: row[i].time }))
  .sort((a, b) => a.time - b.time);

Lo fai solo per la manciata di candidati più vicini, quindi resta una singola chiamata poco costosa e non una per negozio.

Passo 4: renderizzare i negozi su una mappa

L'ultimo passaggio è la mappa stessa. Aggiungi un marker per ogni negozio ordinato, un popup con indirizzo e orari di apertura, e inquadra la vista in modo che tutti i risultati siano visibili. Con una API di mappe che serve tile, geocoding e ricerca da un unico provider, l'intero store locator poggia su un solo fornitore e un solo sistema di coordinate, end to end: è esattamente ciò su cui è costruita la mappa mostrata prima in questo articolo.

Dai a ogni marker un popup con l'essenziale che serve al visitatore per agire: nome, indirizzo, distanza, orari di apertura e un link «Indicazioni» che passa la coordinata a un motore di routing.

I dettagli che separano una demo dalla produzione

Risultati vuoti. Qualcuno cerca da una regione dove non hai punti vendita. Decidi in anticipo se allargare automaticamente il raggio, mostrare il singolo negozio più vicino per quanto lontano sia, oppure dire onestamente «nessun negozio entro 50 km».

Orari di apertura. Uno store locator che mostra come opzione più vicina un negozio chiuso è frustrante. Filtra o segnala in base agli orari, così che «aperto ora» diventi un'opzione di primo livello.

Input ambigui. «Cambridge» esiste in Inghilterra e in Massachusetts, «Springfield» esiste decine di volte. Il bias per paese nel passaggio di geocoding elimina gran parte del problema, e offrire l'autocomplete mentre il visitatore digita elimina il resto.

GPS mobile e consenso. Su mobile l'esperienza migliore è il pulsante «usa la mia posizione», ma leggere il GPS del dispositivo significa trattare dati di posizione e richiede il consenso. Chiedi prima, e torna all'input testuale se il visitatore rifiuta.

Privacy. La posizione del visitatore è un dato personale nel momento in cui viene collegata a lui. Geocodifica on demand, evita di memorizzare la coordinata grezza e usa una API basata nell'UE così che la posizione non lasci mai il SEE. Per il quadro completo, vedi la nostra guida alle mappe conformi al GDPR.

Costruire uno store locator con MapAtlas

MapAtlas ti dà l'intera pipeline da una sola API e un solo sistema di coordinate. La Geocoding API trasforma CAP e città in coordinate con bias per paese; tu ordini il tuo elenco di punti vendita rispetto a quella coordinata; le API Directions e Matrix riordinano i migliori candidati per tempo di percorrenza reale; e le tile di Dynamic Maps renderizzano il risultato, esattamente come mostrato in questo articolo. Poiché tutto gira all'interno dell'UE per impostazione predefinita, la posizione del visitatore resta nel SEE, il che mantiene lo store locator conforme al GDPR senza lavoro aggiuntivo.

I formati completi di request e response per ogni endpoint sono nella documentazione della API MapAtlas. Vale la pena dare un'occhiata anche alla Search API se vuoi che lo store locator scopra i punti di interesse attorno al visitatore, non solo i tuoi punti vendita.

Uno store locator è una funzione piccola con dentro parecchio giudizio silenzioso: capire input vaghi, ordinare per prossimità genuina e rispettare il fatto che una posizione è un dato personale. Azzecca questi tre aspetti e il box «trova il negozio più vicino» smette di essere un ripensamento e diventa una delle cose più usate del tuo sito.