Começar

Introdução

Com os URLs do Maps, você pode criar um URL universal em várias plataformas para abrir o Google Maps e fazer pesquisas, ver rotas e navegar, além de exibir visualizações de mapa e imagens panorâmicas. A sintaxe do URL é a mesma, independentemente da plataforma em uso.

Você não precisa de uma chave de API do Google para usar os URLs do Maps.

Sintaxe universal em várias plataformas

Como desenvolvedor de um app Android, iOS ou site, você pode criar um URL comum. Ele abrirá o Google Maps e realizará a ação solicitada, independentemente da plataforma usada quando o mapa for aberto.

  • Em um dispositivo Android, faça o seguinte:
    • Se o app Google Maps para Android estiver instalado e ativo, o URL abrirá o Google Maps no app Maps e realizará a ação solicitada.
    • Se o app Google Maps não estiver instalado ou desativado, o URL abrirá o Google Maps em um navegador e executará a ação solicitada.
  • Em um dispositivo iOS:
    • Se o app Google Maps para iOS estiver instalado, o URL abrirá o Google Maps no app Maps e realizará a ação solicitada.
    • Se o app Google Maps não estiver instalado, o URL abrirá o Google Maps em um navegador e executará a ação solicitada.
  • Em qualquer outro dispositivo, o URL abre o Google Maps em um navegador e realiza a ação solicitada.

É recomendável usar um URL multiplataforma para abrir o Google Maps no seu app ou site, já que esses URLs universais permitem lidar de forma mais abrangente com as solicitações de mapas, independentemente da plataforma em uso. Para recursos que podem funcionar apenas em uma plataforma para dispositivos móveis (por exemplo, navegação guiada), use uma opção específica para a plataforma Android ou iOS. Consulte a seguinte documentação:

Como iniciar o Google Maps e realizar uma ação específica

Para iniciar o Google Maps e, opcionalmente, executar uma das funções compatíveis, use um esquema de URL de uma das seguintes formas, dependendo da ação solicitada:

  • Pesquisa: inicie um mapa do Google Maps que exibe um alfinete para um lugar específico ou faça uma pesquisa geral e inicie um mapa para exibir os resultados:
    https://www.google.com/maps/search/?api=1&parameters
  • Rotas: solicite rotas e inicie o Google Maps com os resultados:
    https://www.google.com/maps/dir/?api=1&parameters
  • Exibir um mapa — inicie o Google Maps sem marcadores ou rotas:
    https://www.google.com/maps/@?api=1&map_action=map&parameters
  • Mostrar um panorama do Street View – inicie uma imagem de panorama interativa:
    https://www.google.com/maps/@?api=1&map_action=pano&parameters

Importante: o parâmetro api=1 identifica a versão dos URLs do Maps a que esse URL se destina. Esse parâmetro é obrigatório em todas as solicitações. O único valor válido é 1. Se api=1 NÃO estiver presente no URL, todos os parâmetros serão ignorados e o app Google Maps padrão será iniciado, seja em um navegador ou no app para dispositivos móveis, dependendo da plataforma em uso (por exemplo, https://www.google.com/maps).

Como criar URLs válidos

Você precisa codificar os URLs corretamente.

Por exemplo, alguns parâmetros usam uma barra vertical (|) como separador, que precisa ser codificado como %7C no URL final. Outros parâmetros usam valores separados por vírgula, como coordenadas de latitude/longitude ou cidade, estado. Codifique a vírgula como %2C. Codifique os espaços com %20 ou substitua-os por um sinal de adição (+).

Além disso, os URLs são limitados a 2.048 caracteres para cada solicitação. Esteja ciente desse limite ao criar seus URLs.

Ações no mapa

As ações disponíveis no mapa são: pesquisa, rotas, exibir um mapa e um panorama do Street View. Especifique a ação no URL da solicitação, com os parâmetros obrigatórios e opcionais. Como é padrão em URLs, separe os parâmetros usando o caractere "e" comercial (&). Para cada ação, a lista de parâmetros e os possíveis valores deles estão enumerados na seção Parâmetros de pesquisa.

Pesquisa

A ação exibe os resultados de uma pesquisa na região visível do mapa. Ao pesquisar um lugar específico, o mapa resultante adiciona um alfinete ao local especificado e exibe os detalhes disponíveis.

Como criar o URL de pesquisa

https://www.google.com/maps/search/?api=1&parameters

Parâmetros

  • query (obrigatório): define os lugares a serem destacados no mapa. O parâmetro de consulta é obrigatório para todas as solicitações de pesquisa.
    • Especifique os locais como nome de endereço, endereço ou coordenadas de latitude/longitude separadas por vírgulas. As strings precisam ser codificadas em URL. Por isso, um endereço como "City Hall, New York, NY" precisa ser convertido em City+Hall%2C+New+York%2C+NY.
    • Especifique termos de pesquisa gerais como uma string codificada em URL, como grocery+stores ou restaurants+in+seattle+wa.
  • query_place_id (opcional): um ID do lugar é um identificador textual que identifica um lugar de forma exclusiva. Para a ação search, especifique um query, mas também é possível especificar um query_place_id. Se você especificar os dois parâmetros, o query só vai ser usado se o Google Maps não encontrar o ID do lugar. Se você está tentando criar um link para um estabelecimento específico, o ID de lugar é a melhor forma de garantir a vinculação ao lugar certo. Também é recomendável enviar um query_place_id ao consultar um local específico usando coordenadas de latitude/longitude.

Exemplos de pesquisa

Pesquisa de local

Em uma pesquisa de local, você procura um local específico usando um nome de lugar, endereço ou coordenadas de latitude/longitude separadas por vírgulas e o mapa resultante exibe um alfinete nesse local. Esses três exemplos ilustram as pesquisas pelo mesmo local, o CenturyLink Field (um estádio esportivo em Seattle, WA), usando diferentes valores de local.

Exemplo 1: a pesquisa do nome do local "CenturyLink Field" resulta no seguinte mapa:

https://www.google.com/maps/search/?api=1&query=centurylink+field

Exemplo 2: pesquisar o campo CenturyLink usando coordenadas de latitude/longitude, bem como o ID de local, resulta no mapa a seguir:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393&query_place_id=ChIJKxjxuaNqkFQR3CK6O1HNNqY

Exemplo 3: pesquisar o campo CenturyLink usando apenas coordenadas de latitude/longitude resulta no mapa a seguir. Há um alfinete no mapa, mas nenhuma outra informação do lugar é fornecida no mapa ou no painel lateral:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393

Pesquisa categórica

Em uma pesquisa categórica, você transmite um termo de pesquisa geral, e o Google Maps tenta encontrar fichas que correspondam aos seus critérios próximos ao local especificado. Se nenhum local for especificado, o Google Maps tentará encontrar fichas por perto do seu local atual. Se você preferir fornecer um local para uma pesquisa categórica, inclua-o na string de pesquisa geral (por exemplo, pizza+seattle+wa).

Neste exemplo, uma pesquisa por pizzarias em Seattle, WA, resulta no seguinte mapa:

https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa


Rotas

A ação "Rotas" mostra o caminho entre dois ou mais pontos especificados no mapa, bem como a distância e o tempo de viagem.

Como criar o URL das rotas

https://www.google.com/maps/dir/?api=1&parameters

Parâmetros

  • origin: define o ponto de partida a partir do qual exibir as rotas. O padrão é o local de início mais relevante, como a localização do dispositivo, se disponível. Se nenhum for definido, o mapa resultante pode fornecer um formulário em branco para permitir que um usuário insira a origem. O valor pode ser um nome de lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgulas. Uma string precisa ser codificada em URL. Portanto, um endereço como "Prefeitura, Nova York, NY" precisa ser convertido em City+Hall%2C+New+York%2C+NY.

    Observação: esse parâmetro é opcional, a menos que você especifique um origin_place_id no URL. Se você especificar um origin_place_id, também será necessário incluir um origin no URL.

  • origin_place_id (opcional): um ID do lugar é um identificador textual que identifica um lugar de forma exclusiva. Se você está tentando especificar um estabelecimento de maneira definitiva, usar um ID de lugar é a melhor garantia para a vinculação ao lugar certo. Os URLs que usam esse parâmetro também precisam incluir um origin.
  • destination: define o endpoint das rotas. Se nenhum for exibido, o mapa resultante pode fornecer um formulário em branco para permitir que o usuário insira o destino. O valor pode ser um nome de lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgulas. Uma string precisa ser codificada em URL. Portanto, um endereço como "Prefeitura, Nova York, NY" precisa ser convertido em City+Hall%2C+New+York%2C+NY.

    Observação:esse parâmetro é opcional, a menos que você especifique um destination_place_id no URL. Se você especificar um destination_place_id, também será necessário incluir um destination no URL.

  • destination_place_id (opcional): um ID do lugar é um identificador textual que identifica um lugar de forma exclusiva. Se você está tentando especificar um estabelecimento de maneira definitiva, usar um ID de lugar é a melhor garantia para a vinculação ao lugar certo. Os URLs que usam esse parâmetro também precisam incluir um destination.
  • travelmode (opcional): define o método de viagem. As opções são: driving, walking (que dá preferência a vias para pedestres e calçadas, quando disponíveis), bicycling (que faz rotas por ciclovias e ruas preferenciais, quando disponível) ou transit. Se nenhum travelmode for especificado, o Google Maps mostrará um ou mais dos modos mais relevantes para a rota especificada e/ou as preferências do usuário.
  • dir_action=navigate (opcional): inicia a navegação guiada ou visualização de rota para o destino especificado, dependendo da origem estar ou não disponível. Se o usuário especificar uma origem e não estiver perto da localização atual do usuário ou se a localização atual do dispositivo estiver indisponível, o mapa iniciará uma visualização de trajeto. Se o usuário não especificar uma origem (nesse caso, usar como padrão a localização atual do dispositivo) ou se a origem estiver próxima à localização atual do usuário, o mapa iniciará a navegação passo a passo. A navegação não está disponível em todos os produtos do Google Maps e/ou entre todos os destinos. Nesses casos, esse parâmetro será ignorado.
  • waypoints: especifica um ou mais lugares intermediários para encaminhar rotas entre origin e destination. É possível especificar vários waypoints usando a barra vertical (|) para separar os lugares (por exemplo, Berlin,Germany|Paris,France). O número de waypoints permitido varia de acordo com a plataforma em que o link é aberto, com até três waypoints compatíveis com navegadores para dispositivos móveis. No máximo, nove waypoints são aceitos. Os pontos de referência são exibidos no mapa na mesma ordem em que estão listados no URL. Cada ponto de referência pode ser um nome de lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgulas. As strings precisam ser codificadas por URL. Assim, os pontos de referência como "Berlim,Alemanha|Paris,França" precisam ser convertidos em Berlin%2CGermany%7CParis%2CFrance.

    Observações:

    • Não há suporte para pontos de referência em todos os produtos do Google Maps. Nesses casos, esse parâmetro será ignorado.
    • Esse parâmetro é opcional, a menos que você especifique waypoint_place_ids no URL. Se você optar por especificar waypoint_place_ids, também precisará incluir waypoints no URL.
  • waypoint_place_ids (opcional): um ID do lugar é um identificador textual que identifica um lugar de forma exclusiva. Waypoint_place_ids permite fornecer uma lista de IDs de local para corresponder à lista de waypoints. Os IDs de lugar precisam ser listados na mesma ordem dos waypoints e separados usando a barra vertical "|" (codificado pelo URL como %7C). Se você estiver tentando especificar definitivos determinados estabelecimentos, os IDs de lugar são a melhor garantia para a vinculação aos locais certos. Os URLs que usam esse parâmetro também precisam incluir waypoints.

Exemplos de rotas

O URL a seguir inicia um mapa no modo de rotas e fornece um formulário para permitir que o usuário insira a origem e o destino.

https://www.google.com/maps/dir/?api=1

O exemplo a seguir lança um mapa com rotas de bicicleta desde o Space Needle até o Pike Place Market, em Seattle, WA.

https://www.google.com/maps/dir/?api=1&origin=Space+Needle+Seattle+WA&destination=Pike+Place+Market+Seattle+WA&travelmode=bicycling

O exemplo a seguir lança um mapa com rotas do Google em Sydney, Austrália, para o Queen Victoria Building.

https://www.google.com/maps/dir/?api=1&origin=Google+Pyrmont+NSW&destination=QVB&destination_place_id=ChIJISz8NjyuEmsRFTQ9Iw7Ear8&travelmode=walking


Exibir um mapa

A ação do mapa retorna um mapa sem marcadores ou rotas.

Como criar o URL do mapa

https://www.google.com/maps/@?api=1&map_action=map&parameters

Parâmetros

  • map_action=map (obrigatório): especifica o tipo de visualização de mapa a ser exibida. O Maps e o Street View compartilham o mesmo endpoint. Para garantir que um mapa seja exibido, o map_action precisa ser especificado como map.
  • center (opcional): define o centro da janela do mapa e aceita coordenadas de latitude/longitude como valores separados por vírgula (por exemplo, -33.8569,151.2152).
  • zoom (opcional): define o nível de zoom inicial do mapa. Os valores aceitos são números inteiros que variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados de mapa disponíveis no local selecionado. O padrão é 15.
  • basemap (opcional): define o tipo de mapa a ser exibido. O valor pode ser roadmap (padrão), satellite ou terrain.
  • layer (opcional): define uma camada extra para exibição no mapa, se houver. O valor pode ser um dos seguintes: none (padrão), transit, traffic ou bicycling.

Exemplos de mapas

Este URL de exemplo inicia um mapa do Google padrão, centralizado na localização atual do usuário.

https://www.google.com/maps/@?api=1&map_action=map

O exemplo a seguir exibe um mapa centralizado em Katoomba, NSW, Austrália (em -33.712206,150.311941), e define os parâmetros opcionais zoom e basemap.

https://www.google.com/maps/@?api=1&map_action=map&center=-33.712206%2C150.311941&zoom=12&basemap=terrain


Exibir um panorama do Street View

A ação de panorama permite iniciar um visualizador para exibir imagens do Street View como panoramas interativos. Cada panorama do Street View oferece uma visualização completa de 360 graus de um único local. As imagens contêm 360 graus de exibição horizontal (uma volta completa) e 180 graus de visualização vertical (de cima para baixo). A ação de panorama inicia um visualizador que renderiza o panorama resultante como uma esfera com uma câmera no centro. É possível manipular a câmera para controlar o zoom e a orientação.

O Google Street View oferece vistas panorâmicas de locais designados em toda a área de cobertura. Fotos esféricas contribuídas por usuários e coleções especiais do Street View também estão disponíveis.

Como criar o URL do Street View

https://www.google.com/maps/@?api=1&map_action=pano&parameters

Parâmetros

  • map_action=pano (obrigatório): especifica o tipo de visualização que será exibido. O Maps e o Street View compartilham o mesmo endpoint. Para garantir que um panorama seja exibido, o action precisa ser especificado como pano.

Um dos seguintes parâmetros de URL também é obrigatório:

  • viewpoint: o visualizador exibe o panorama fotografado mais próximo do local viewpoint, especificado como coordenadas de latitude/longitude separadas por vírgula (por exemplo, 46.414382,10.013988). Como as imagens do Street View são atualizadas periodicamente e as fotos podem ser tiradas de posições um pouco diferentes a cada vez, é possível que seu local seja ajustado a um panorama diferente quando as imagens forem atualizadas.
  • pano: o ID do panorama específico da imagem a ser exibida. Se você especificar um pano, também poderá especificar um viewpoint. O viewpoint será usado apenas se o Google Maps não encontrar o ID do panorama. Se pano for especificado, mas não encontrado, e um viewpoint NÃO for especificado, nenhuma imagem de panorama será exibida. Em vez disso, o Google Maps é aberto no modo padrão, exibindo um mapa centralizado no local atual do usuário.

Os seguintes parâmetros de URL são opcionais:

  • heading: indica a direção da bússola da câmera em graus no sentido horário a partir do Norte. Os valores aceitos vão de -180 a 360 graus. Se omitido, um título padrão é escolhido com base no ponto de vista (se especificado) da consulta e no local real da imagem.
  • pitch: especifica o ângulo da câmera para cima ou para baixo. A inclinação é especificada em graus de -90 a 90. Valores positivos inclinam a câmera para cima, enquanto valores negativos a inclinam para baixo. O valor padrão de 0 é definido com base na posição da câmera quando a imagem foi capturada. Por isso, um argumento de venda de 0 costuma ser horizontal, mas nem sempre. Por exemplo, uma imagem capturada em uma colina provavelmente terá um valor padrão de inclinação não horizontal.
  • fov: determina o campo de visão horizontal da imagem. O campo de visão é expresso em graus, com um intervalo de 10 a 100. O padrão é 90. Ao lidar com uma janela de visualização de tamanho fixo, o campo de visão é considerado o nível de zoom, com números menores indicando um nível maior de zoom.

Exemplos do Street View

Os dois primeiros exemplos mostram um panorama da Torre Eiffel. No exemplo, um usa apenas um viewpoint para o local e define os parâmetros opcionais heading, pitch e fov. Para fins de comparação, o segundo exemplo usa um ID pano e os mesmos parâmetros definidos no primeiro exemplo. O terceiro mostra uma imagem de panorama interna.

Exemplo 1: usa apenas um viewpoint para especificar o local.

https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

Exemplo 2: usa um ID pano e um local viewpoint. O ID pano tem precedência sobre a viewpoint. Neste exemplo, o ID do panorama é encontrado, então o viewpoint é ignorado. Observe que a imagem do panorama que é exibida para o ID pano é um pouco diferente e mais recente do que a imagem encontrada usando apenas o viewpoint.

https://www.google.com/maps/@?api=1&map_action=pano&pano=tu510ie_z4ptBZYo2BGEJg&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

Exemplo 3: exibe um panorama do interior do restaurante Sarastro em Londres, Reino Unido, especificado com um ID de panorama.

https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

Como encontrar um ID do panorama

Para encontrar o ID de uma imagem de panorama específica, há vários métodos que você pode usar.

Mais exemplos

Exemplos de rotas usando waypoints

Os exemplos de rotas a seguir iniciam o Google Maps e exibem rotas de carro de Paris, na França para Cherbourg, na França, traçando os seguintes pontos de referência:

Cidade, paísNome do localID do lugar
1. Versalhes, França Palácio de Versalhes ChIJdUyx15R95kcRj85ZX8H8OAU
2. Chartres, França Catedral de Chartres ChIJKzGHdEgM5EcR_OBTT3nQoEA
3. Le Mans, França Catedral de São Juliano de Le Mans ChIJG2LvQNCI4kcRKXNoAsPi1Mc
4. Caen, França Castelo de Caen ChIJ06tnGbxCCkgRsfNjEQMwUsc

Nos URLs de exemplo, os waypoints são definidos de maneiras diferentes para que você possa comparar as diferenças na exibição deles nos mapas resultantes.

Exemplo 1: pontos de referência definidos como cidade e país:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance

Exemplo 2: pontos de referência definidos como nomes de lugares específicos:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Palace+of+Versailles%7CChartres+Cathedral%7CCathedral+of+Saint+Julian+of+Le+Mans%7CCaen+Castle

Exemplo 3: pontos de referência definidos como cidade e país e também fornece waypoint_place_ids para um estabelecimento específico em cada ponto de referência:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance&waypoint_place_ids=ChIJdUyx15R95kcRj85ZX8H8OAU%7CChIJKzGHdEgM5EcR_OBTT3nQoEA%7CChIJG2LvQNCI4kcRKXNoAsPi1Mc%7CChIJ06tnGbxCCkgRsfNjEQMwUsc

Exemplo 4: define waypoints como cidade e país, mas lista os waypoints em uma ordem diferente em relação aos exemplos anteriores. Demonstra que o mapa mostra waypoints na ordem em que estão listados no URL.

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CCaen%2CFrance%7CLe+Mans%2CFrance%7CChartres%2CFrance

Exemplos de mapas

Exibe um mapa com um basemap especificado (satélite) e um layer (transporte público).

https://www.google.com/maps/@?api=1&map_action=map&center=37.7992940%2C-122.3976113&zoom=15&basemap=satellite&layer=transit

Exemplos do Street View

Exibe um panorama do Street View usando uma chave de imagem FIFE como o ID pano. Observe que o ID da pano é precedido por F:.

https://www.google.com/maps/@?api=1&map_action=pano&pano=F:-ud6AZSB-sQg/V0cfCSV3OWI/AAAAAAAAG1U/UQEoc5sXPQEIP7zzD6SWzmKb8Vbug47uQCLIB&heading=22&pitch=-5&fov=55