Como integrar um mapa de mobilidade no seu site?

Para integrar um mapa de mobilidade em seu site sem construir toda a interface, use um iframe ROOTE. O embed pode receber uma busca de cidade e filtros adaptados à página: bicicletas para um guia de bike, banheiros para um guia de sanitários, ônibus e tram para transportes.

Os exemplos deste guia usam embed.roote.ai, o domínio integrado nos guias ROOTE. A documentação geral também descreve a integração de map.roote.ai e diferencia os parâmetros de câmera daqueles de uma pesquisa completa.

Adicionar um iframe responsivo

Este bloco abre uma busca por bicicleta em Bordeaux com zoom 15. A URL é construída no código; o título do iframe descreve seu conteúdo para leitores de tela. Adapte este título ao idioma da sua página.

<iframe
  title="Carte ROOTE — vélos à Bordeaux"
  src="https://embed.roote.ai/?q=Bordeaux&amp;modes=bicycle&amp;zoom=15"
  width="100%"
  height="480"
  loading="lazy"
  allow="geolocation"
  style="display:block; width:100%; min-height:360px; border:0; border-radius:16px;"
></iframe>

Num atributo HTML, os separadores & são escritos como &. A largura de 100% segue a do contêiner. Mantenha uma altura utilizável em dispositivos móveis e evite colocar controles indispensáveis fora da área visível.

Escolher os modos correspondentes à página

Esses valores pertencem ao percurso embed ROOTE conectado às categorias mobilidade, serviços e trânsito. Eles não substituem os parâmetros REST: Serviços usa types, enquanto Trânsito usa modes. Um mapa centrado em uma cidade não garante que cada categoria tenha resultados nela.

Diferenciar a câmera e a origem da pesquisa

lat e lon posicionam a câmera. Eles não são suficientes, no contrato documentado do mapa, para criar uma busca por proximidade. Para restaurar uma pesquisa conhecida, use search_lat, search_lon e search_label, junto com modos e zoom.

https://embed.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=15&modes=bus,tram

As coordenadas acima são um ponto de referência em Bordeaux, não a posição do usuário. Se também adicionar parâmetros de câmera, pode mostrar outra área ao manter o ponto usado para distâncias. Faça isso somente se essa separação for desejada.

Documentação dos parâmetros do mapa ROOTE

Construir uma URL sem perder caracteres especiais

Use URL e URLSearchParams em vez de concatenação manual. Isso codifica os espaços, acentos e separadores. Este código é destinado ao navegador e cria o endereço do iframe a partir de um local digitado.

const embedUrl = new URL('https://embed.roote.ai/');
embedUrl.searchParams.set('q', 'Place des Quinconces, Bordeaux');
embedUrl.searchParams.set('modes', 'bicycle,toilets');
embedUrl.searchParams.set('zoom', '15');
document.querySelector('iframe').src = embedUrl.toString();

Manter o contexto para o mapa completo

Um link para map.roote.ai deve manter o estado atual da pesquisa se você o conhece. Recriar uma URL sem seus parâmetros perde a cidade, os modos ou o zoom. Mantenha um objeto URL comum durante as atualizações feitas pela sua página.

const fullMapUrl = new URL('https://map.roote.ai/');
fullMapUrl.search = embedUrl.search;
const link = document.querySelector('[data-open-map]');
link.href = fullMapUrl.toString();
link.target = '_blank';
link.rel = 'noopener noreferrer';

Este código mantém os parâmetros conhecidos pela página pai. Se o usuário modificar a pesquisa dentro do iframe, o pai não pode ler diretamente sua URL em outro domínio. Para obter esse estado, é necessário um mecanismo implementado e documentado explicitamente, por exemplo, uma troca postMessage com validação de origem. Não invente nomes de eventos não fornecidos pelo embed.

Gerenciar localização e interações móveis

allow="geolocation" permite que o iframe solicite localização, sujeito ao consentimento e às políticas de permissão do site. Uma recusa deve deixar a busca por cidade utilizável. Não peça a posição assim que o leitor chegar numa página se ele não escolheu essa ação.

Em um artigo, ativar voluntariamente o mapa pode evitar que sua rolagem ou zoom capturem gestos durante a leitura. O controle deve permanecer acessível pelo teclado e claramente nomeado. Verifique mudanças de orientação e tela estreita, não apenas a versão desktop.

Verificar o resultado e estados de falha

Teste cada filtro, uma cidade conhecida, uma área com poucos dados, uma busca inválida e uma categoria indisponível. Um mapa sem marcador não informa sozinho se a busca está vazia ou com problema. Mantenha mensagens do embed e acesso utilizável ao mapa completo.

Diferenciar ausência de resultado e erro de API

Escolher entre embed, API e MCP

Exemplo de guia para encontrar banheiros

Perguntas frequentes

É necessário colocar uma chave API no iframe?

As URLs públicas mostradas aqui não contêm. Não coloque segredo em uma URL de embed ou no código cliente.

zoom=15 aumenta o raio da busca?

O zoom regula a vista. Não o confunda com o raio de uma requisição API; verifique os parâmetros de busca da interface usada.

O pai conhece as alterações feitas no iframe?

Ele conhece os parâmetros que transmite. Modificações internas exigem um mecanismo de troca documentado entre os dois domínios.