Comece já

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.

Não é necessário ter uma chave de API do Google para usar URLs do Maps.

Sintaxe universal de várias plataformas

Como desenvolvedor de um app Android, iOS ou um site, você pode criar um URL comum, que abre o Google Maps e realiza a ação solicitada, independentemente da plataforma em uso quando o mapa é aberto.

  • Em um dispositivo Android:
    • Se o app Google Maps para Android estiver instalado e ativo, o URL vai iniciar o Google Maps no app e realizar a ação solicitada.
    • Se o app não estiver instalado ou desativado, o URL vai iniciar 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 iniciar o Google Maps no app e realizar a ação solicitada.
    • Se o app não estiver instalado, o URL vai iniciar 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 realiza a ação solicitada.

Recomendamos que você use um URL multiplataforma para iniciar 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), você pode preferir usar uma opção específica da plataforma para 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 um dos seguintes formatos, dependendo da ação solicitada:

  • Pesquisar: inicie um mapa do Google que mostre um alfinete para um lugar específico ou faça uma pesquisa geral e abra um mapa para mostrar os resultados:
    https://www.google.com/maps/search/?api=1&parameters
  • Rotas: solicite rotas e abra o Google Maps com os resultados:
    https://www.google.com/maps/dir/?api=1&parameters
  • Mostrar 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 do panorama interativo:
    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 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

Você precisa codificar corretamente os URLs.

Por exemplo, alguns parâmetros usam uma barra vertical (|) como separador, que você precisa codificar 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 espaços com %20 ou os substitua por um sinal de adição (+).

Além disso, os URLs estã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: pesquisar, rotas e exibir um mapa e um panorama do Street View. Especifique a ação no URL da solicitação com parâmetros obrigatórios e opcionais. Como é padrão em URLs, você separa os parâmetros usando o caractere "e" comercial (&). Para cada ação, a lista de parâmetros e os possíveis valores são enumerados na seção Parâmetros de pesquisa.

Pesquisar

A ação de pesquisa mostra os resultados de uma pesquisa 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&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, endereço ou coordenadas de latitude/longitude separadas por vírgula. As strings precisam ser codificadas em URL. Portanto, endereços como "City Hall, New York, NY" (Prefeitura, Nova York, NY) precisam ser convertidos em City+Hall%2C+New+York%2C+NY (link em inglês).
    • 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 de lugar é um identificador textual que identifica um local de forma exclusiva. Para a ação search, você precisa especificar um query, mas também pode especificar um query_place_id. Se você especificar os dois parâmetros, o query será usado apenas se o Google Maps não conseguir encontrar o ID de lugar. Se você estiver tentando vincular de forma definitiva a 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

Na pesquisa de local, quando você procura um local específico usando o nome, endereço ou coordenadas de latitude/longitude separadas por vírgula, o mapa mostra um alfinete no local. Estes três exemplos ilustram pesquisas do mesmo local, o CenturyLink Field (um estádio esportivo em Seattle, WA), usando valores de localização diferentes.

Exemplo 1: a pesquisa do nome de lugar "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 lugar, resulta no seguinte mapa:

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 gera resultados no mapa a seguir. Observe que há um alfinete no mapa, mas nenhuma outra informação sobre o 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 perto do local especificado. Se nenhum local for especificado, o Google Maps tentará encontrar fichas perto da sua localização atual. Caso prefira informar 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, traz o seguinte mapa:

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

Directions

A ação Directions exibe o caminho entre dois ou mais pontos especificados no mapa, além da distância e do tempo de viagem.

Como formar o URL de rotas

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

Parâmetros

  • origin: define o ponto de partida de onde mostrar as rotas. O padrão é o local de partida mais relevante, como a localização do dispositivo, se disponível. Se não houver nenhum, o mapa resultante pode mostrar um formulário em branco para que o usuário insira a origem. O valor pode ser o nome de um lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgula. Uma string precisa ser codificada em URL. Assim, um endereço como "City Hall, New York, NY" (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ê optar por especificar um origin_place_id, também vai precisar incluir um origin no URL.

  • origin_place_id (opcional): um ID de lugar é um identificador textual que identifica um local de forma exclusiva. Se você está tentando especificar definitivamente um estabelecimento, o uso de um ID de lugar é a melhor garantia de que você vai incluir o link para o lugar certo. Os URLs que usam esse parâmetro também precisam incluir um origin.
  • destination: define o endpoint das rotas. Se não houver nenhum, o mapa resultante poderá mostrar um formulário em branco para que o usuário insira o destino. O valor pode ser o nome de um lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgula. Uma string precisa ser codificada em URL. Assim, um endereço como "City Hall, New York, NY" (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 precisará incluir um destination no URL.

  • destination_place_id (opcional): um ID de lugar é um identificador textual que identifica um local de forma exclusiva. Se você está tentando especificar definitivamente um estabelecimento, o uso de um ID de lugar é a melhor garantia de que você vai incluir o link para o lugar certo. Os URLs que usam esse parâmetro também precisam incluir um destination.
  • travelmode (opcional): define o meio de transporte. As opções são driving, walking (que dá preferência a caminhos para pedestres e calçadas, quando disponível), bicycling (trajetos por ciclovias e ruas preferenciais, quando disponíveis) ou transit. Se nenhum travelmode for especificado, o mapa mostrará um ou mais dos modos mais relevantes para o trajeto e/ou as preferências do usuário especificados.
  • dir_action=navigate (opcional): inicia a navegação guiada ou a visualização do trajeto até o destino especificado, dependendo da disponibilidade da origem. Se o usuário especificar uma origem e ela não estiver perto da localização atual dele ou se a localização atual do dispositivo não estiver disponível, o mapa vai iniciar uma visualização do trajeto. Se o usuário não especificar uma origem (o padrão é a localização atual do dispositivo) ou ela estiver próxima da localização atual do usuário, o mapa 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 rotear rotas entre origin e destination. É possível especificar vários waypoints usando o caractere de barra vertical (|) para separar lugares (por exemplo, Berlin,Germany|Paris,France). O número de waypoints permitido varia de acordo com a plataforma em que o link é aberto, sendo que até três waypoints são aceitos em navegadores para dispositivos móveis. Caso contrário, são aceitos no máximo nove waypoints. Os waypoints são exibidos no mapa na mesma ordem em que estão listados no URL. Cada waypoint pode ser o nome de um lugar, um endereço ou coordenadas de latitude/longitude separadas por vírgula. As strings precisam ser codificadas para URL. Assim, waypoints como "Berlim,Alemanha|Paris,França" precisam ser convertidos em Berlin%2CGermany%7CParis%2CFrance.

    Notes:

    • 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_ids no URL. Se você optar por especificar waypoint_place_ids, também precisará incluir waypoints no URL.
  • waypoint_place_ids (opcional): um ID de lugar é um identificador textual que identifica um local de forma exclusiva. Waypoint_place_ids permite que você forneça uma lista de IDs de lugares que correspondem à lista de waypoints. Os IDs de lugares precisam ser listados na mesma ordem que os waypoints e separados por uma barra vertical "|" ( codificado por URL como %7C). Se você está tentando especificar definitivamente determinados estabelecimentos, os IDs de lugar são a melhor garantia de que você vai criar links para os lugares certos. Os URLs que usam esse parâmetro também precisam incluir waypoints.
  • avoid (opcional): define os recursos que a rota precisa tentar evitar. Ele pode ser definido como uma ou mais destas opções, separadas por uma vírgula "," ( codificado por URL como %2C):
    • ferries
    • highways
    • tolls

Exemplos de rotas

O URL a seguir abre 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 inicia um mapa com rotas de bicicleta do Space Needle para 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 inicia um mapa com rotas a pé do Google de Sydney, na Austrália, até 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 "map" retorna um mapa sem marcadores ou rotas.

Como formar 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 ponto de extremidade. Para garantir que um mapa seja mostrado, 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í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 inteiros de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo varia de acordo com os 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 a ser mostrada no mapa, se houver. O valor pode ser um dos seguintes: none (padrão), transit, traffic ou bicycling.

Exemplos de mapas

Esse URL de exemplo inicia um mapa padrão do Google Maps, 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, 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

Mostrar 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 fornece 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 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 dela.

O Google Street View oferece vistas panorâmicas de locais designados em toda a área de cobertura. Também há fotosferas de contribuição de usuários e coleções especiais do Street View.

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 a ser exibido. O Maps e o Street View compartilham o mesmo ponto de extremidade. Para garantir que um panorama seja exibido, o action precisa ser especificado como pano.

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

  • viewpoint: o visualizador mostra 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 fotografias podem ser tiradas de posições ligeiramente diferentes a cada vez, é possível que seu local passe para 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 só será usado se o Google Maps não conseguir 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, 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 cabeçalho padrão é escolhido com base no ponto de vista (se especificado) da consulta e na localização 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. O valor padrão de inclinação é definido com base na posição da câmera quando a imagem foi capturada. Por isso, um valor de 0 é, muitas vezes, mas não sempre, horizontal. 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. O exemplo 1 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, bem como os mesmos parâmetros definidos no primeiro exemplo. O terceiro exemplo mostra uma imagem de panorama interno.

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 o viewpoint. Neste exemplo, o ID do panorama foi encontrado, então viewpoint é ignorado. A imagem de panorama exibida para o ID pano é um pouco diferente e mais recente do que a imagem encontrada usando apenas 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: 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 específica do panorama, você pode usar vários métodos.

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 até Cherbourg, França, passando pelos seguintes waypoints:

Cidade, paísNome do localID do lugar
1. Versalhes, França O 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 dos waypoints nos mapas resultantes.

Exemplo 1: waypoints definidos como cidade, 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: waypoints 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: waypoints definidos como cidade, país e também fornece waypoint_place_ids para um estabelecimento específico em cada waypoint:

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, País, mas lista os waypoints em uma ordem diferente dos exemplos anteriores. Demonstra que o mapa exibe 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 (satélite) e um layer especificados (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

Mostra um panorama do Street View usando uma chave de imagem FIFE como o ID pano. O ID 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