Como Adicionar Mapas ao Seu App: Embeds, Mapas Interativos e Localizadores de Lojas

Para adicionar um mapa ao seu app, primeiro decida se você precisa de um embed estático (um local com um marcador, como “encontre a nossa loja”) ou de um mapa interativo (muitos marcadores vindos dos seus dados, filtros, agrupamento, “perto de mim”). Para um único local, um mapa incorporado é a forma mais rápida e, com a Maps Embed API do Google, gratuita. 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 provedor de tiles. Guarde a latitude e a longitude de cada local no seu banco de dados e restrinja a chave de API ao seu próprio domínio. Os detalhes de fornecedores abaixo vêm da documentação de cada provedor, em setembro de 2026.

Que tipo de mapa você 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.

Suas opções

Google Maps Platform

O guia de início do Google diz que você precisa criar um projeto no Cloud com faturamento ativado e habilitar as APIs que quer usar. O preço pay-as-you-go oferece SKUs Essentials, incluindo Dynamic Maps, com um limite gratuito de 10.000 eventos mensais, e lista o Dynamic Maps a US$ 7,00 por 1.000 eventos acima disso (na primeira faixa de volume). O SKU Maps Embed aparece como ilimitado e gratuito. O Google também vende planos mensais de assinatura. Confira a página de preços do Google Maps Platform para os números atuais.

Mapbox

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

Leaflet e OpenStreetMap

O Leaflet se descreve como uma biblioteca JavaScript de código aberto para mapas interativos adaptados a celulares, com cerca de 42 KB de JavaScript. Ele precisa de tiles de mapa (as imagens do mapa) de algum lugar. Os servidores públicos de tiles do OpenStreetMap são tentadores, mas a política de uso de tiles exige atribuição visível, proíbe download 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 hospedada por você que funcione com o Leaflet.

Chaves de API: públicas, mas restritas

Chaves de mapa usadas no navegador são visíveis para qualquer pessoa que abra a sua página. Isso é esperado, mas significa que alguém pode copiar a sua chave e gerar uso na sua conta. A orientação de segurança do Google é adicionar restrições de website (referenciador HTTP) listando os seus domínios, e restrições de API para que a chave só funcione nas APIs que você usa.

Chaves para serviços do lado do servidor — geocodificar milhares de endereços, por exemplo — devem ser chaves separadas, guardadas em segredos do servidor, e não na página. Configure também alertas de orçamento ou cotas no console do provedor, para que um erro não vire uma conta grande.

Geocodificação: transforme endereços em coordenadas uma vez

Mapas plotam latitude e longitude, não endereços. Converter um endereço em coordenadas chama-se geocodificação, e a maioria dos provedores cobra por requisição. O padrão eficiente:

1. Quando um anúncio é salvo, geocodifique o endereço no servidor.
2. Guarde a latitude e a longitude no banco de dados.
3. O mapa lê as coordenadas guardadas; ele nunca faz geocodificação ao exibir a página.

Confira os termos de cada provedor sobre por quanto tempo você pode guardar os resultados de geocodificação; eles variam.

Prompts de exemplo

Um único mapa incorporado:

Na página de Contato, adicione um mapa do Google incorporado mostrando o nosso endereço (12 High Street, Leeds) usando a Maps Embed API, com a chave em GOOGLE_MAPS_EMBED_KEY. Adicione um link “Como chegar” embaixo. Deixe-o com largura total em celulares e use carregamento preguiçoso (lazy-load).

Um mapa interativo de anúncios:

Adicione latitude e longitude à tabela de anúncios. Quando um anúncio for criado ou seu endereço mudar, geocodifique-o no servidor com a chave em GEOCODING_API_KEY e salve as coordenadas. Na página Explorar, mostre um mapa com um marcador por anúncio usando Leaflet, com agrupamento quando os marcadores se sobrepuserem. Clicar em um marcador mostra o título, o preço e um link. O mapa e a lista devem usar os mesmos filtros.

“Perto de mim”:

Adicione um botão “Perto de mim” que pede a localização do visitante e mostra os anúncios em até 10 km, ordenados por distância. Se ele recusar o acesso à localização, permita digitar uma cidade.

Passo a passo

1. Escolha o tipo de mapa pela tabela do início.
2. Crie a conta no provedor e um projeto, e habilite apenas as APIs de que precisa.
3. Crie as chaves: uma chave para o navegador restrita aos seus domínios (incluindo o domínio de preview enquanto constrói) e, se necessário, uma chave para o servidor para geocodificação.
4. Guarde as chaves como segredos e peça ao seu construtor para usá-las; a chave do navegador continua restrita mesmo acabando na página.
5. Guarde as coordenadas de cada local no banco de dados.
6. Construa o mapa: marcadores, pop-ups, agrupamento e um zoom inicial sensato.
7. Combine com uma lista. Um mapa sozinho é difícil de usar em celulares e para leitores de tela. Mostre os mesmos resultados em forma de lista.
8. Configure um alerta de orçamento no console do provedor.
9. Publique e teste no domínio no ar, já que as restrições de referenciador muitas vezes bloqueiam o mapa até que o domínio publicado seja adicionado.

Erros comuns

• Chaves sem restrição. Qualquer um pode reutilizá-las no próprio site.
• Geocodificar a cada visualização de página. Lento e caro; geocodifique uma vez, ao salvar.
• Esquecer o domínio publicado nas restrições da chave. Funciona no preview, mas aparece uma caixa cinza em branco em produção.
• Layouts só com o mapa. Pinos sem lista são difíceis em telas pequenas e inacessíveis.
• Centenas de marcadores sem agrupamento. Ilegível e lento.
• Atribuição ausente. A maioria dos provedores de mapas e tiles exige atribuição, e ocultá-la quebra os termos deles.
• Pedir a localização ao carregar a página. Peça apenas quando o usuário tocar em “Perto de mim”.

Checklist

• Tipo de mapa certo para o trabalho escolhido
• Chave do navegador restrita aos seus domínios e às APIs necessárias
• Chaves do lado do servidor guardadas em segredos
• Coordenadas guardadas no banco 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 provedor
• Testado no domínio publicado e em um celular

Adicionando mapas com o Mythex

O Mythex não tem integração de mapas embutida; você traz a sua própria chave de provedor, adiciona-a como segredo do projeto (ou cola quando o agente mostrar um cartão de segredos) e pede o mapa no chat, como descrito em Integre qualquer API. As coordenadas vão para o banco de dados do projeto. Lembre-se de adicionar tanto o seu domínio de preview quanto o publicado às restrições de website da chave, e publique de novo após alterar os segredos.

Mapas costumam ficar ao lado de busca e listagens: veja como adicionar busca ao seu app, como criar um site de diretório e como criar um site para pequenos negócios.

Perguntas