Introdução
Com os URLs do Maps, você pode criar um URL universal multiplataforma 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.
Não é necessário ter uma chave de API do Google para usar os URLs do Maps.
Sintaxe multiplataforma universal
Como desenvolvedor de um app Android, um app iOS ou um site, você pode criar um URL comum, que abrirá o Google Maps e executará a ação solicitada, independentemente da plataforma em uso quando o mapa for aberto.
- Em um dispositivo Android:
- Se o app Google Maps para Android estiver instalado e ativo, o URL vai abrir o Google Maps no app e realizar a ação solicitada.
- Se o app Google Maps não estiver instalado ou estiver desativado, o URL vai abrir o Google Maps em um navegador e realizar a ação solicitada.
- Em um dispositivo iOS:
- Se o app Google Maps para iOS estiver instalado, o URL vai abrir o Google Maps no app Maps e realizar a ação solicitada.
- Se o app Google Maps não estiver instalado, o URL vai abrir o Google Maps em um navegador e realizar a ação solicitada.
- Em qualquer outro dispositivo, o URL inicia o Google Maps em um navegador e executa a ação solicitada.
Recomendamos 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 dos mapas, independentemente da plataforma em uso. Para recursos que só funcionam em uma plataforma móvel (por exemplo, navegação guiada), use uma opção específica para Android ou iOS. Consulte a seguinte documentação:
- Intents do Google Maps para Android: especificamente para iniciar o app Google Maps para Android
- Esquema de URL do Google Maps para iOS, especificamente para iniciar o app Google Maps para iOS
Iniciar o Google Maps e realizar uma ação específica
Para iniciar o Google Maps e, se quiser, executar uma das funções compatíveis, use um esquema de URL de uma das seguintes formas, dependendo da ação solicitada:
- Pesquisa: inicia o Google Maps com um alfinete em um lugar específico ou realiza uma pesquisa genérica e inicia um mapa para mostrar os resultados:
https://www.google.com/maps/search/?api=1¶meters - Rotas:
solicite rotas e inicie o Google Maps com os resultados:
https://www.google.com/maps/dir/?api=1¶meters - Mostrar um mapa: inicia o Google Maps sem marcadores ou rotas:
https://www.google.com/maps/@?api=1&map_action=map¶meters - Criar uma lista de favoritos
— abra o Google Maps com uma lista de lugares específicos:
https://www.google.com/maps/@?api=1&map_action=shortlist¶meters - Mostrar um panorama do Street View
— iniciar uma imagem panorâmica interativa:
https://www.google.com/maps/@?api=1&map_action=pano¶meters
Importante: o parâmetro api=1 identifica a versão dos
URLs do Maps a que este 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 em um navegador ou no app Google Maps para dispositivos móveis, dependendo da plataforma em uso (por exemplo, https://www.google.com/maps).
Como criar URLs válidos
É necessário codificar corretamente os URLs.
Por exemplo, alguns parâmetros usam uma barra vertical
(|) como separador, que precisa ser codificada como %7C
no URL final. Outros parâmetros usam valores separados por vírgulas, 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 estão limitados a 2.048 caracteres para cada solicitação. Tenha em mente esse limite ao criar seus URLs.
Ações no mapa
As ações disponíveis no mapa são: pesquisar, traçar rotas, exibir um mapa, criar uma lista de favoritos e exibir um panorama do Street View. Você especifica a ação no URL da solicitação, junto 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 são enumerados na seção Parâmetros de pesquisa.
Pesquisar
A ação de pesquisa mostra resultados para uma busca na região visível do mapa. Ao pesquisar um lugar específico, o mapa resultante coloca um alfinete no local especificado e mostra os detalhes disponíveis.
Como formar o URL de pesquisa
https://www.google.com/maps/search/?api=1¶meters
Parâmetros
query(obrigatório): define os lugares que serão destacados no mapa. O parâmetro de consulta é obrigatório para todas as solicitações de pesquisa.- Especifique os locais como um nome de lugar, endereço ou coordenadas de latitude/longitude separadas por vírgula. As strings precisam ser
codificadas em URL. Portanto, um endereço
como "City Hall, New York, NY" precisa ser convertido em
City+Hall%2C+New+York%2C+NY. - Especifique termos de pesquisa genérica como uma string codificada em URL, como
grocery+storesourestaurants+in+seattle+wa.
- Especifique os locais como um nome de lugar, endereço ou coordenadas de latitude/longitude separadas por vírgula. As strings precisam ser
codificadas em URL. Portanto, um endereço
como "City Hall, New York, NY" precisa ser convertido em
query_place_id(opcional): um ID de lugar é um identificador textual que identifica um local de forma exclusiva. Para a açãosearch, é necessário especificar umquery, mas também é possível especificar umquery_place_id. Se você especificar os dois parâmetros, oquerysó será usado se o Google Maps não encontrar o ID de lugar. Se você estiver tentando vincular definitivamente a um estabelecimento específico, o ID de lugar é a melhor garantia de que você vai vincular ao lugar certo. Também é recomendável enviar umquery_place_idao consultar um local específico usando coordenadas de latitude/longitude.
Exemplos de pesquisa
Pesquisa de local
Em uma pesquisa de local, você busca um local específico usando um nome, endereço ou coordenadas de latitude/longitude separadas por vírgulas, e o mapa resultante mostra um alfinete nesse local. Estes três exemplos mostram pesquisas para o mesmo local usando valores diferentes.
Exemplo 1: pesquisar o nome do lugar "Lumen Field" resulta no seguinte mapa:
https://www.google.com/maps/search/?api=1&query=lumen+field

Exemplo 2: pesquisar o Lumen Field usando apenas coordenadas de latitude/longitude resulta no mapa a seguir. Observe que há um alfinete no mapa, mas nenhuma informação adicional sobre o lugar é fornecida no mapa ou no painel lateral:
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393

Exemplo 3: pesquisar o Lumen Field usando coordenadas de latitude/longitude e o ID de lugar resulta no seguinte mapa:

Exemplo 4: pesquisar o nome de lugar "Starbucks" resulta no seguinte mapa:
https://www.google.com/maps/search/?api=1&query=starbucks

Exemplo 5: pesquisar um Starbucks específico usando o nome e o ID de lugar resulta no seguinte mapa:
https://www.google.com/maps/search/?api=1&query=starbucks&query_place_id=ChIJsU30zM1qkFQRbnOm1_LBoG0

Quando sua meta é mostrar os detalhes de um lugar específico, crie os URLs de pesquisa usando um dos seguintes formatos recomendados:
query=PLACE_NAME,ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
Para recuperar IDs de lugar de maneira programática, use os recursos da API Places: Pesquisa de texto(somente ID). Esse é um método sem custo financeiro para conseguir IDs de lugar. Saiba mais sobre o ID de lugar e a solicitação da API Place(nova).
Os IDs de lugar também podem ser recuperados quando um usuário clica ou toca em um PDI nos mapas. Saiba mais detalhes sobre ícones de PDI clicáveis (JavaScript, Android, iOS)
Pesquisa categórica
Em uma pesquisa por categoria, você transmite um termo de pesquisa genérica, e o Google Maps tenta encontrar listagens que correspondam aos seus critérios perto do local especificado.
Se nenhum local for especificado, o Google Maps vai tentar encontrar fichas de empresas perto da sua localização 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 de rotas mostra o caminho entre dois ou mais pontos especificados no mapa, além da distância e do tempo de viagem.
Como criar o URL de rotas
https://www.google.com/maps/dir/?api=1¶meters
Parâmetros
origin: define o ponto de partida para mostrar rotas. O padrão é o local de partida mais relevante, como o local do dispositivo, se disponível. Se não houver, o mapa resultante poderá fornecer um formulário em branco para que o usuário insira a origem. O valor pode ser um nome de lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgula. Uma string precisa ser codificada em URL. Portanto, um endereço como "City Hall, New York, NY" precisa ser convertido emCity+Hall%2C+New+York%2C+NY.Observação: esse parâmetro é opcional, a menos que você especifique um
origin_place_idno seu URL. Se você especificar umorigin_place_id, também precisará incluir umoriginno URL.origin_place_id(opcional): um ID de lugar é um identificador textual que identifica um lugar de forma exclusiva. Se você estiver tentando especificar um estabelecimento de forma definitiva, usar um ID de lugar é a melhor garantia de que você vai vincular ao lugar certo. Os URLs que usam esse parâmetro também precisam incluir umorigin.destination: define o endpoint das rotas. Se nenhum for fornecido, o mapa resultante poderá fornecer um formulário em branco para que o usuário insira o destino. O valor pode ser um nome de local, um endereço ou coordenadas de latitude/longitude separadas por vírgulas. Uma string precisa ser codificada em URL. Portanto, um endereço como "City Hall, New York, NY" precisa ser convertido emCity+Hall%2C+New+York%2C+NY.Observação: esse parâmetro é opcional, a menos que você especifique um
destination_place_idno URL. Se você optar por especificar umdestination_place_id, também será necessário incluir umdestinationno URL.destination_place_id(opcional): um ID de lugar é um identificador textual que identifica um local de forma exclusiva. Se você estiver tentando especificar um estabelecimento de forma definitiva, usar um ID de lugar é a melhor garantia de que você vai vincular ao lugar certo. Os URLs que usam esse parâmetro também precisam incluir umdestination.travelmode(opcional): define o método de viagem. Confira a lista de opções:drivingwalking: prefere vias de pedestres e calçadas, quando disponíveis.bicycling: rotas por ciclovias, quando disponíveis. "Bicicleta" se refere ao meio de transporte movido por humanos.two-wheeler: trajetos por ruas preferidas para veículos de duas rodas, quando disponíveis. "Veículo de duas rodas" se refere a veículos motorizados de duas rodas, como motocicletas. Para mais informações, consulte Cobertura para veículos de duas rodas.transitdir_action=navigate(opcional): inicia a navegação trecho a trecho ou a prévia do trajeto até o destino especificado, dependendo da disponibilidade da origem. Se o usuário especificar uma origem que não esteja perto da localização atual dele ou se a localização atual do dispositivo não estiver disponível, o mapa vai mostrar uma prévia do trajeto. Se o usuário não especificar uma origem (nesse caso, o padrão é o local atual do dispositivo) ou se a origem estiver próxima do local atual do usuário, o mapa vai iniciar a navegação guiada. 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 traçar rotas entreoriginedestination. É possível especificar vários pontos de referência usando o caractere de barra vertical (|) para separar os lugares (por exemplo,Berlin,Germany|Paris,France). O número de pontos de referência permitidos varia de acordo com a plataforma em que o link é aberto, com até três pontos de referência em navegadores para dispositivos móveis e um máximo de nove pontos de referência em outros casos. Os pontos de referência são mostrados no mapa na mesma ordem em que aparecem no URL. Cada ponto de passagem pode ser um nome de lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgulas. As strings precisam ser codificadas em URL. Portanto, pontos de passagem como "Berlin,Germany|Paris,France" precisam ser convertidos emBerlin%2CGermany%7CParis%2CFrance.Observações:
- Os waypoints não são compatíveis com todos os produtos do Google Maps. Nesses casos, esse parâmetro será ignorado.
- Esse parâmetro é opcional, a menos que você especifique
waypoint_place_idsno URL. Se você especificarwaypoint_place_ids, também precisará incluirwaypointsno URL.
waypoint_place_ids(opcional): um ID de lugar é um identificador textual que identifica um local de forma exclusiva.Waypoint_place_idspermite fornecer uma lista de IDs de lugar para corresponder à lista dewaypoints. Os IDs de lugar precisam ser listados na mesma ordem dos pontos de referência e separados usando o caractere de barra vertical "|" ( com codificação de URL como%7C). Se você estiver tentando especificar definitivamente determinados estabelecimentos, os IDs de lugar são a melhor garantia de que você vai vincular aos lugares certos. Os URLs que usam esse parâmetro também precisam incluirwaypoints.avoid(opcional): define recursos que o trajeto deve tentar evitar. Ele pode ser definido como uma ou mais dessas opções, separadas por uma vírgula "," ( codificada para uso em URL como%2C):ferrieshighwaystolls
travelmode for especificado, o Google Maps vai mostrar
um ou mais dos meios de transporte mais relevantes para o trajeto especificado e/ou as preferências do usuário.
Exemplos de rotas
O URL a seguir inicia um mapa no modo de rotas e fornece um formulário para que o usuário insira a origem e o destino.
https://www.google.com/maps/dir/?api=1

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

O exemplo a seguir inicia um mapa com rotas para veículos de duas rodas do Google Mumbai até o Aeroporto Internacional de Mumbai.
.
O exemplo a seguir inicia um mapa com rotas a pé do Google Sydney, Austrália, até o Queen Victoria Building.

Exibir um mapa
A ação do mapa retorna um mapa sem marcadores ou rotas.
Como formar o URL do mapa
https://www.google.com/maps/@?api=1&map_action=map¶meters
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, omap_actionprecisa ser especificado comomap.center(opcional): define o centro da janela do mapa e aceita coordenadas de latitude/longitude como valores separados por vírgulas (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 de 0 (o mundo todo) 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 serroadmap(padrão),satelliteouterrain.layer(opcional): define uma camada extra para mostrar no mapa, se houver. O valor pode ser um dos seguintes:none(padrão),transit,trafficoubicycling.
Exemplos de mapas
Este exemplo de URL inicia um Google Maps padrão, centralizado na localização atual do usuário.
https://www.google.com/maps/@?api=1&map_action=map

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

Mostrar um panorama do Street View
A ação de panorama permite iniciar um visualizador para mostrar imagens do Street View como panoramas interativos. Cada panorama do Street View oferece uma visualização completa em 360 graus de um único local. As imagens contêm 360 graus de visualização horizontal (uma volta completa) e 180 graus de visualização vertical (de cima para baixo). A ação pano 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 dela.
O Google Street View oferece vistas panorâmicas de locais designados em toda a área de cobertura. As fotos esféricas enviadas por usuários e as coleções especiais do Street View também estão disponíveis.
Como formar o URL do Street View
https://www.google.com/maps/@?api=1&map_action=pano¶meters
Parâmetros
map_action=pano(obrigatório): especifica o tipo de visualização a ser exibida. O Maps e o Street View compartilham o mesmo endpoint. Para garantir que um panorama seja exibido, oactionprecisa ser especificado comopano.
Um dos seguintes parâmetros de URL também é obrigatório:
viewpoint: o visualizador mostra o panorama fotografado mais próximo do localviewpoint, especificado como coordenadas de latitude/longitude separadas por vírgulas (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 ligeiramente diferentes a cada vez, é possível que seu local seja ajustado para um panorama diferente quando as imagens forem atualizadas.pano: o ID do panorama específico da imagem a ser mostrada. Se você especificar umpano, também poderá especificar umviewpoint. Oviewpointsó será usado se o Google Maps não encontrar o ID do panorama. Sepanofor especificado, mas não for encontrado, e umviewpointNÃO for especificado, nenhuma imagem panorâmica será mostrada. Em vez disso, o Google Maps abre no modo padrão, mostrando um mapa centralizado na localização 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 será escolhido com base no ponto de vista (se especificado) da consulta e no local real da imagem.pitch: especifica o ângulo, para cima ou para baixo, da câmera. 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. A inclinação padrão de 0 é definida com base na posição da câmera quando a imagem foi capturada. Por isso, uma inclinação de 0 é frequentemente, mas nem sempre, horizontal. Por exemplo, uma imagem capturada em uma colina provavelmente terá um valor padrão de inclinação que 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 de zoom mais alto.
Exemplos do Street View
Os dois primeiros exemplos mostram um panorama da Torre Eiffel. O 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 exemplo dois usa um ID pano e os mesmos parâmetros definidos no primeiro exemplo. O terceiro exemplo mostra uma imagem panorâmica interna.
Exemplo 1: usa apenas um viewpoint para especificar o local.

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

Exemplo 3: mostra 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 de panorama
Para encontrar o ID de uma imagem panorâmica específica, há vários métodos que você pode usar.
- Para JavaScript, use a classe StreetViewPanorama.
- Para Android, use a classe pública StreetViewPanoramaLocation.
- No iOS, use a classe GMSPanorama.
- Também é possível fazer solicitações de metadados usando a API Google Street View Image. As solicitações de metadados de imagens fornecem dados sobre panoramas do Street View, incluindo o ID do panorama.
Criar uma lista
A ação de lista mostra uma lista de lugares específicos e permite que o usuário os salve no perfil do Google Maps, compartilhe com outras pessoas ou explore cada lugar individualmente.
Como formar o URL da lista
https://www.google.com/maps/@?api=1&map_action=shortlist¶meters
Parâmetros
map_action=shortlist(obrigatório): especifica a ação de lista de finalistas.place_ids(obrigatório): define os lugares a serem incluídos na lista. Esse parâmetro aceita um ou mais IDs de lugar como valores separados por vírgulas. É possível especificar no máximo 20 IDs de lugar.
Exemplo de lista de candidatos
O exemplo a seguir inicia um mapa com uma lista curta contendo três lugares específicos.
Mais exemplos
Exemplos de rotas usando waypoints
Os exemplos de rotas a seguir iniciam o Google Maps e mostram rotas de carro de Paris, França, para Cherbourg, França, passando pelos seguintes pontos de referência:
| Cidade, país | Nome do local | ID 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 Saint Julian 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, país:

Exemplo 2: waypoints definidos como nomes de lugares específicos:

Exemplo 3: waypoints definidos como cidade e país, além de fornecer
waypoint_place_ids para um estabelecimento específico em cada waypoint:

Exemplo 4: define waypoints como cidade e país, mas lista os waypoints em uma ordem diferente em comparação com os exemplos anteriores. Demonstra que o mapa mostra os pontos de referência na ordem em que estão listados no URL.

Exemplos de mapas
Mostra um mapa com um basemap (satélite) e um layer (transporte público) especificados.

Exemplos do Street View
Mostra um panorama do Street View usando uma chave de imagem FIFE como o ID do pano. O ID pano é precedido por F:.

Como melhorar os URLs do Maps com parâmetros UTM
Para ajudar o Google a entender melhor como os desenvolvedores estão integrando URLs do Maps e garantir a performance ideal,
recomendamos que você inclua parâmetros de acompanhamento UTM na construção do URL. Ao adicionar os parâmetros utm_source e utm_campaign, você fornece dados valiosos que nos permitem analisar padrões de uso e melhorar o produto URLs do Maps.
Para o parâmetro utm_source, use o nome do seu aplicativo. O parâmetro utm_campaign precisa refletir a ação pretendida pelo usuário, como "location_sharing", "place_details_search" ou "directions_request".
Por exemplo, um URL com parâmetros UTM pode ser assim:
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YOUR_APP_NAME&utm_campaign=place_details_search