Um store locator, ou localizador de lojas, é aquele recurso pequeno que todo negócio com várias filiais acaba precisando: a caixinha de "encontre a loja mais próxima" que transforma um CEP em uma lista curta e ranqueada de lojas no mapa. De fora parece trivial, e o caminho feliz é genuinamente simples, mas um bom store locator faz três trabalhos bem feitos e em silêncio: entende entrada de localização bagunçada, ranqueia filiais por proximidade real e renderiza o resultado em um mapa no qual um humano consegue agir.
Este guia mostra como um store locator funciona de verdade, os quatro passos para construir um com uma API de mapas e os detalhes que separam uma demo de algo que você colocaria em produção. Todo mapa deste artigo é renderizado com a própria API do MapAtlas.
O que um Store Locator Realmente Faz
Tire a estilização e um store locator é um pipeline com três estágios:
- Geocode da entrada do visitante. "1012 Amsterdam", "01310-100" ou uma posição de GPS compartilhada, todos precisam virar uma única latitude e longitude.
- Ranking por proximidade das lojas. Dada essa coordenada e a sua lista de filiais, encontre as mais próximas dentro de um raio sensato.
- Render dos resultados. Coloque as lojas ranqueadas no mapa como marcadores, cada uma com endereço, horário de funcionamento e um link para a rota.
O mapa abaixo é exatamente esse terceiro estágio, renderizado com tiles do MapAtlas: seis filiais no centro de Amsterdã marcadas por distância a partir do visitante. Aqui elas são supermercados, mas o mapa é idêntico quer os marcadores venham de um dataset de POIs, quer venham da sua própria lista de lojas.
A ordem das cores é o ranking. O visitante buscou a partir do centro do mapa, e os marcadores são as filiais mais próximas em ordem, da mais perto para a mais longe.
Passo 1: Geocodifique a Entrada do Visitante
O visitante digita um CEP, uma cidade ou um endereço completo, e você precisa de uma coordenada. Isso é 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"
Dois detalhes importam aqui. Passe um focus.point perto da sua área de atuação para que "Cambridge" resolva na cidade certa, e trate o caso em que o visitante compartilha o GPS do dispositivo em vez de digitar: aí você já tem a coordenada e pula esse passo inteiro.
Passo 2: Ranqueie Suas Lojas por Distância
Agora você tem a coordenada do visitante. As lojas em si são o seu próprio dado: uma lista de filiais, cada uma com latitude e longitude, que vive no seu banco. Ranquear é um cálculo de distância em linha reta (haversine), sem nenhuma chamada de 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);
É tudo o que um locator básico precisa. Para uma rede grande, você primeiro filtraria por um bounding box ao redor do visitante para não medir distância até cada filial em cada request, e só então ordenaria os sobreviventes. A saída é uma lista curta das filiais mais próximas, cada uma com um distance_m.
Passo 3: Ranqueie por Distância, Depois Refine por Tempo de Deslocamento
Distância em linha reta é o default certo. É rápida, não precisa de chamada extra e, para uma rede densa, geralmente está correta. Mas a loja mais próxima em linha reta nem sempre é a mais rápida de alcançar: uma loja a 400 metros do outro lado de um rio pode virar um desvio de dez minutos até a ponte mais próxima.
Para um locator em que "mais próxima" realmente significa "mais rápida de chegar", re-ranqueie os poucos primeiros candidatos por tempo real de deslocamento com uma chamada de directions ou 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);
Você só faz isso para o punhado de candidatos mais próximos, então continua sendo uma única chamada barata, não uma por loja.
Passo 4: Renderize as Lojas em um Mapa
O passo final é o mapa em si. Solte um marcador para cada loja ranqueada, adicione um popup com endereço e horário de funcionamento, e enquadre a visualização para que todo resultado fique visível. Com uma API de mapas que serve tiles, geocoding e busca de um provedor só, o locator inteiro é um fornecedor e um sistema de coordenadas de ponta a ponta, que é exatamente sobre o que o mapa lá em cima neste artigo foi construído.
Dê a cada marcador um popup com o essencial para o visitante agir: nome, endereço, distância, horário de funcionamento e um link de "Rotas" que entrega a coordenada para um motor de roteamento.
Detalhes Que Separam uma Demo da Produção
Resultados vazios. Alguém busca a partir de uma região onde você não tem filial. Decida de antemão se vai ampliar o raio automaticamente, mostrar a única loja mais próxima por mais longe que ela esteja, ou dizer honestamente "nenhuma loja num raio de 50 km".
Horário de funcionamento. Um locator que mostra uma loja como a opção mais próxima quando ela está fechada é frustrante. Filtre ou sinalize por horário de funcionamento para que "aberto agora" seja uma opção de primeira classe.
Entrada ambígua. "Cambridge" existe na Inglaterra e em Massachusetts; "Springfield" existe dezenas de vezes. Enviesar por país no passo do geocode remove a maior parte disso, e oferecer autocomplete enquanto o visitante digita remove o resto.
GPS móvel e consentimento. No mobile, a experiência mais forte é o botão "usar minha localização", mas ler o GPS do dispositivo é dado de localização e exige consentimento. Peça primeiro, e caia de volta para a entrada de texto se o visitante recusar.
Privacidade. A localização do visitante é dado pessoal no momento em que está ligada a ele. Geocodifique sob demanda, evite armazenar a coordenada bruta e use uma API sediada na UE para que a localização nunca saia do EEE. Veja nosso guia de mapas compatíveis com GDPR para o quadro completo.
Construindo um Store Locator com MapAtlas
O MapAtlas entrega o pipeline inteiro a partir de uma API e um sistema de coordenadas. A Geocoding API transforma CEPs e cidades em coordenadas com enviesamento por país; você ranqueia a sua própria lista de filiais contra essa coordenada; as APIs de Directions e Matrix re-ranqueiam os primeiros candidatos por tempo real de deslocamento; e os tiles de Dynamic Maps renderizam o resultado, exatamente como mostrado neste artigo. Como tudo roda dentro da UE por padrão, a localização do visitante fica no EEE, o que mantém o locator compatível com GDPR sem trabalho extra.
Os formatos completos de request e response de cada endpoint estão na documentação da API do MapAtlas. A Search API também vale uma olhada se você quiser que o locator descubra pontos de interesse ao redor do visitante, não só as suas próprias filiais.
Um store locator é um recurso pequeno com muito julgamento silencioso dentro dele: entender entrada vaga, ranquear por proximidade genuína e respeitar o fato de que uma localização é dado pessoal. Acerte esses três e a caixinha de "encontre a loja mais próxima" deixa de ser um detalhe de última hora e passa a ser uma das coisas mais usadas do seu site.
Perguntas frequentes
O que é um store locator?
Um store locator, ou localizador de lojas, é o recurso de 'encontre uma loja perto de você' em sites de varejo e serviços. O visitante digita um CEP, uma cidade ou compartilha a localização, e o locator devolve as filiais mais próximas ranqueadas por distância, cada uma marcada no mapa com endereço, horário de funcionamento e link de rota. Por baixo do capô são três passos: geocodificar a entrada para uma coordenada, rodar uma busca por proximidade contra a sua lista de locais e renderizar os resultados em um mapa.
Como construir um store locator?
Construa um store locator em quatro passos. Primeiro, geocodifique a entrada do visitante (CEP ou cidade) em latitude e longitude com uma API de geocoding. Segundo, rode uma consulta por raio ou por vizinho mais próximo contra as coordenadas das suas lojas para pegar as filiais mais próximas. Terceiro, ordene esses resultados por distância e, opcionalmente, por tempo de deslocamento. Quarto, renderize as lojas ranqueadas como marcadores em um mapa com popups. Uma API de mapas que entrega geocoding, busca por proximidade e tiles de mapa de um provedor só permite fazer os quatro passos sem costurar serviços diferentes.
Preciso de uma store locator API?
Você precisa de geocoding, tiles de mapa e normalmente de ranking por tempo de viagem; a lista de lojas em si é o seu próprio dado. Dá para hardcodar uma lista curta de lojas e calcular distância em linha reta na mão, mas no momento em que você quer busca por CEP, ordenação por tempo de trajeto e um mapa renderizado, uma API que combina geocoding, matrix e renderização de mapa em um provedor só evita amarrar três fornecedores e reconciliar os formatos de coordenada de cada um.
Como um store locator ranqueia as lojas mais próximas?
O ranking mais simples é a distância em linha reta (great-circle) da coordenada do visitante até cada loja, em ordem crescente. É rápido e suficiente para redes urbanas densas. Para uma experiência melhor, re-ranqueie os primeiros candidatos por tempo real de deslocamento usando uma chamada de directions ou matrix, porque a loja mais próxima em linha reta nem sempre é a mais rápida de alcançar quando entram rios, rodovias e ruas de mão única.
Um store locator é compatível com GDPR?
Pode ser, e onde o visitante está na UE ele precisa ser. Um store locator processa uma localização, que é dado pessoal quando ligada a um usuário. Mantenha a conformidade geocodificando sob demanda em vez de armazenar a coordenada do visitante, usando uma API de mapas sediada na UE para que a localização nunca saia do EEE, e pedindo consentimento antes de ler o GPS do dispositivo. A MapAtlas processa consultas de localização dentro da UE por padrão.
