Como Adicionar Mapas à Sua App: Incorporações, Mapas Interativos e Localizadores de Lojas

Para adicionar um mapa à sua app, decida primeiro se precisa de uma incorporação estática (um local com um marcador, como «encontre a nossa loja») ou de um mapa interativo (muitos marcadores a partir dos seus dados, filtros, agrupamento, «perto de mim»). Para um único local, um mapa incorporado é o mais rápido e, com a Maps Embed API da Google, gratuito. Para mapas interativos, use uma biblioteca de mapas em JavaScript — Google Maps JavaScript API, Mapbox GL JS ou o Leaflet de código aberto com um fornecedor de tiles — guarde a latitude e a longitude de cada local na sua base de dados e restrinja a sua chave de API ao seu próprio domínio. Os detalhes dos fornecedores abaixo vêm da documentação de cada um, a partir de setembro de 2026.

Que tipo de mapa precisa?

A maioria dos sites de pequenos negócios só precisa da primeira linha. Diretórios, marketplaces e sites de listagens precisam da terceira e da quarta.

As suas opções

Google Maps Platform

O guia de introdução da Google diz que tem de criar um projeto do Cloud com faturação ativa e ativar as APIs que quer usar. O preço pay-as-you-go da Google dá-lhe SKUs Essentials, incluindo Dynamic Maps, com um limite gratuito de 10.000 eventos por mês, e indica o Dynamic Maps a 7,00 USD por 1.000 eventos acima disso (no primeiro escalão de volume). O SKU do Maps Embed aparece como ilimitado e gratuito. A Google também vende planos mensais por subscrição. Consulte o preço do Google Maps Platform para os números atuais.

Mapbox

A página de preços da Mapbox indica 50.000 carregamentos de mapas gratuitos por mês para o Mapbox GL JS na web, depois 5,00 USD por 1.000 carregamentos. Veja preços da Mapbox.

Leaflet e OpenStreetMap

O Leaflet descreve-se como uma biblioteca de JavaScript de código aberto para mapas interativos adaptados a dispositivos móveis, com cerca de 42 KB de JavaScript. Precisa de tiles de mapa (as imagens do mapa) de algum lado. Os servidores públicos de tiles do OpenStreetMap são tentadores, mas a política de utilização de tiles exige atribuição visível, proíbe o descarregamento em massa, não oferece garantia de serviço e avisa que serviços comerciais podem perder o acesso. Para um produto real, use uma fonte de tiles comercial ou alojada por si que funcione com o Leaflet.

Chaves de API: públicas, mas restritas

As chaves de mapas usadas no browser ficam visíveis para quem abrir a sua página. Isso é esperado, mas significa que alguém pode copiar a sua chave e gerar consumo na sua fatura. As orientações de segurança da Google são adicionar restrições de website (HTTP referrer) com os seus domínios, e restrições de API para que a chave só funcione nas APIs que usa.

As chaves para serviços do lado do servidor — por exemplo, geocodificar milhares de moradas — devem ser chaves separadas guardadas nos segredos do servidor, e não na página. Configure também alertas de orçamento ou quotas na consola do fornecedor, para que um erro não se transforme numa fatura grande.

Geocodificação: converter moradas em coordenadas uma vez

Os mapas marcam latitude e longitude, não moradas. Converter uma morada em coordenadas chama-se geocodificação, e a maioria dos fornecedores cobra por pedido. O padrão eficiente:

1. Quando um anúncio é guardado, geocodifique a sua morada no servidor.
2. Guarde a latitude e a longitude na base de dados.
3. O mapa lê as coordenadas guardadas; nunca geocodifica ao ser visualizado.

Verifique os termos de cada fornecedor sobre quanto tempo pode guardar os resultados de geocodificação; eles variam.

Exemplos de prompts

Um mapa incorporado:

Na página de Contactos, adicione um mapa Google incorporado a mostrar a nossa morada (12 High Street, Leeds) usando a Maps Embed API com a chave em GOOGLE_MAPS_EMBED_KEY. Adicione por baixo uma ligação «Obter direções». Ocupe a largura total nos telemóveis e use carregamento preguiçoso (lazy).

Um mapa interativo de anúncios:

Adicione latitude e longitude à tabela de anúncios. Quando um anúncio é criado ou a sua morada muda, geocodifique-a no servidor com a chave em GEOCODING_API_KEY e guarde as coordenadas. Na página Explorar, mostre um mapa com um marcador por anúncio usando Leaflet, com agrupamento quando os marcadores se sobrepõem. Clicar num marcador mostra o título, o preço e uma ligação. O mapa e a lista devem usar os mesmos filtros.

«Perto de mim»:

Adicione um botão «Perto de mim» que peça a localização do visitante e mostre os anúncios a menos de 10 km, ordenados por distância. Se recusar o acesso à localização, deixe-o escrever uma cidade.

Passo a passo

1. Escolha o tipo de mapa na tabela do início.
2. Crie a conta no fornecedor e um projeto, e ative apenas as APIs de que precisa.
3. Crie as chaves: uma chave para o browser restrita aos seus domínios (incluindo o domínio de Preview enquanto constrói) e, se for preciso, uma chave de servidor para geocodificação.
4. Guarde as chaves como segredos e peça ao construtor que as use; a chave do browser continua restrita mesmo acabando na página.
5. Guarde as coordenadas de cada local na base de dados.
6. Construa o mapa: marcadores, pop-ups, agrupamento e um zoom predefinido sensato.
7. Acompanhe-o com uma lista. Um mapa sozinho é difícil de usar num telemóvel e para leitores de ecrã. Mostre os mesmos resultados em lista.
8. Configure um alerta de orçamento na consola do fornecedor.
9. Publique e teste no domínio em produção, já que as restrições de referrer muitas vezes bloqueiam o mapa até o domínio em produção ser adicionado.

Erros comuns

• Chaves sem restrições. Qualquer pessoa pode reutilizá-las no seu próprio site.
• Geocodificar em cada visualização da página. Lento e caro; geocodifique uma vez ao guardar.
• Esquecer o domínio em produção nas restrições da chave. Funciona no Preview, mas fica uma caixa cinzenta vazia em produção.
• Layouts só com mapa. Os marcadores sem lista são incómodos em ecrãs pequenos e inacessíveis.
• Centenas de marcadores sem agrupamento. Ilegível e lento.
• Falta de atribuição. A maioria dos fornecedores de mapas e tiles exige-a, e escondê-la viola os termos deles.
• Pedir a localização ao carregar a página. Peça apenas quando o utilizador toca em «Perto de mim».

Lista de verificação

• Tipo de mapa certo escolhido para o trabalho
• Chave do browser restrita aos seus domínios e às APIs necessárias
• Chaves do lado do servidor guardadas nos segredos
• Coordenadas guardadas na base de dados, geocodificadas uma vez
• Resultados também mostrados como lista
• Agrupamento para muitos marcadores
• Atribuição visível
• Alerta de orçamento configurado com o fornecedor
• Testado no domínio publicado e num telemóvel

Adicionar mapas com a Mythex

A Mythex não tem uma integração de mapas incorporada; traz a sua própria chave de fornecedor, adiciona-a como segredo do projeto (ou cola-a quando o agente mostrar um cartão de segredos) e pede o mapa no chat, como descrito em Integrar qualquer API. As coordenadas vão para a base de dados do projeto. Lembre-se de adicionar tanto o domínio de Preview como o domínio publicado às restrições de website da chave, e publique de novo depois de alterar os segredos.

Os mapas costumam ficar ao lado de pesquisa e listagens: veja como adicionar pesquisa à sua app, como construir um site de diretório e como construir um site para pequenos negócios.

Perguntas