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 de mapas.
Sintaxe universal em várias plataformas
Como desenvolvedor de um app Android, iOS ou de um 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:
- Se o app Google Maps para Android estiver instalado e ativo, o URL iniciará o Google Maps no app Maps e executará 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 iniciará 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 inicia o Google Maps em um navegador e realiza a ação solicitada.
Recomendamos usar um URL multiplataforma para iniciar o Google Maps no seu app ou site, já que esses URLs universais permitem um tratamento mais amplo das solicitações de mapas, independentemente da plataforma em uso. Para recursos que só podem ser funcionais em uma plataforma para dispositivos móveis (por exemplo, navegação passo a passo), convém usar uma opção específica da plataforma para Android ou iOS. Consulte a seguinte documentação:
- Intents do Google Maps para Android: especificamente para lançar o app Google Maps para Android
- Esquema de URL do Google Maps para iOS: especificamente para lançar o app Google Maps para iOS.
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 Maps com um alfinete de um lugar específico ou faça uma pesquisa geral e inicie 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
- Exiba um mapa:
inicie o Google Maps sem marcadores ou rotas:
https://www.google.com/maps/@?api=1&map_action=map¶meters
- Exibir um panorama do Street View: inicie uma imagem de panorama 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 padrão do Google Maps 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.br/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. É necessário codificar a vírgula como %2C
. Codifique os espaços por
%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, exibição de um mapa e um panorama do Street View. Você especifica 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 de"e"comercial (&
). Para cada ação, a lista de parâmetros e os respectivos valores
podem ser enumerados na seção Parâmetros de pesquisa.
Pesquisa
A ação exibe 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 exibe os detalhes disponíveis.
Criar o URL de pesquisa
https://www.google.com/maps/search/?api=1¶meters
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írgula. As strings precisam ser
codificadas para 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 gerais como uma
string codificada por URL, como
grocery+stores
ourestaurants+in+seattle+wa
.
- Especifique os locais como nome de endereço, endereço ou coordenadas de latitude/longitude separadas por vírgula. As strings precisam ser
codificadas para 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
, especifique umquery
, mas também é possível especificar umquery_place_id
. Se você especificar os dois parâmetros, oquery
será usado apenas 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ê vinculará ao lugar certo. Também é recomendável enviar umquery_place_id
ao consultar um local específico usando coordenadas de latitude/longitude.
Exemplos de pesquisa
Pesquisa de local
Em uma pesquisa de local, pesquise um local específico usando um nome de lugar, endereço ou coordenadas de latitude/longitude separadas por vírgulas, e o mapa resultante exibirá um alfinete nesse local. Esses três exemplos ilustram pesquisas pelo mesmo local, o CenturyLink Field (um estádio esportivo em Seattle, WA), usando valores de localização diferentes.
Exemplo 1: pesquisar o 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 lugar, resulta no seguinte mapa:
Exemplo 3: pesquisar o campo CenturyLink usando apenas coordenadas de latitude/longitude no mapa a seguir. Há um alfinete no mapa, mas nenhuma outra informação de 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ê passa 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 do seu local atual. Se você preferir fornecer um local para uma pesquisa categórica, inclua o local 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 Directions mostra o caminho entre dois ou mais pontos especificados no mapa, bem como a distância e o tempo de viagem.
Criar o URL do Directions
https://www.google.com/maps/dir/?api=1¶meters
Parâmetros
origin
: define o ponto de partida a partir do qual as rotas serão exibidas. O padrão será o local de início mais relevante, como a localização do usuário, se disponível. Se nenhum resultado for mostrado, o mapa resultante poderá fornecer um formulário em branco para permitir que um usuário insira a origem. O valor pode ser um nome de local, endereço ou coordenadas de latitude/longitude separadas por vírgula. Uma string precisa ser codificada por 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_id
no URL. Se você optar por especificar umorigin_place_id
, também será necessário incluir umorigin
no URL.origin_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 maneira definitiva, usar um ID de lugar é a melhor garantia para vincular ao lugar certo. Os URLs que usam esse parâmetro também precisam incluir umorigin
.destination
: define o endpoint das rotas. Se nenhum mapa for definido, o mapa resultante mostrará um formulário em branco para permitir que o usuário insira o destino. O valor pode ser um nome de local, endereço ou coordenadas de latitude/longitude separadas por vírgula. Uma string precisa ser codificada por 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_id
no URL. Se você optar por especificar umdestination_place_id
, também será necessário incluir umdestination
no 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 maneira definitiva, usar um ID de lugar é a melhor garantia para vincular ao lugar certo. Os URLs que usam esse parâmetro também precisam incluir umdestination
.travelmode
(opcional): define o método de viagem. As opções sãodriving
,walking
(que prefere vias para pedestres e calçadas, quando disponíveis),bicycling
(que encaminha por ciclovias e ruas preferenciais, quando disponível) outransit
. Se nenhumtravelmode
for especificado, o mapa do Google mostrará um ou mais dos modos mais relevantes para o trajeto especificado e/ou as preferências do usuário.dir_action=navigate
(opcional): inicia o trajeto passo a passo ou a visualização do trajeto para o destino especificado com base na disponibilidade da origem. Se o usuário especificar uma origem e ela não estiver próxima da localização atual do usuário ou se o local atual não estiver disponível, o mapa iniciará uma visualização do trajeto. Se o usuário não especificar uma origem (nesse caso, ela será definida como o local atual do usuário) ou se a origem estiver próxima ao local 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 rotear rotas entreorigin
edestination
. É 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 permitidos varia de acordo com a plataforma em que o link é aberto, com até três waypoints compatíveis com navegadores de 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 waypoint pode ser um nome de local, um endereço ou coordenadas de latitude/longitude separadas por vírgula. As strings precisam ser codificadas por URL. Portanto, waypoints como "Berlim,Alemanha|Paris,França" precisam ser convertidos emBerlin%2CGermany%7CParis%2CFrance
.Observações:
- Os pontos de referência 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 especificarwaypoint_place_ids
, também será necessário incluirwaypoints
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 lugar para corresponder à lista dewaypoints
. Os IDs de local devem ser listados na mesma ordem dos waypoints e separados por uma barra vertical "|
" ( codificadas em URL como%7C
). Se você estiver tentando especificar definitivos certos estabelecimentos, os IDs certos serão os melhores para vincular os locais certos. Os URLs que usam esse parâmetro também precisam incluirwaypoints
.
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 do Space Needle ao Pike Place Market, em Seattle, WA.
O exemplo a seguir lança um mapa com rotas a pé do Google em Sydney, Austrália, para o Queen Victoria Building.
Exibir um mapa
A ação "Map" retorna um mapa sem marcadores ou rotas.
Criar 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_action
precisa ser especificado comomap
.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 inteiros que variam de 0 (todo o mundo) a 21 (edifícios individuais). O limite superior varia de acordo com os dados do 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),satellite
outerrain
.layer
(opcional): define uma camada extra a ser exibida no mapa, se houver. O valor pode ser um dos seguintes:none
(padrão),transit
,traffic
oubicycling
.
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
.
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 em 360 graus de um único local. As imagens contêm 360 graus de visualização horizontal (uma volta completa ao redor de um ponto) e 180 graus de visualização vertical (do ponto mais alto ao mais baixo). A ação de panorama inicia um visualizador que renderiza o panorama resultante como uma esfera e 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. Photo Spheres com contribuições de usuários e coleções especiais do Street View também estão disponíveis.
Criar 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 que será exibida. O Maps e o Street View compartilham o mesmo endpoint. Para garantir que um panorama seja exibido, é necessário especificaraction
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írgula (por exemplo, 46.414382,10.013988). Como as imagens do Street View são atualizadas periodicamente, e as fotos podem ser tiradas em posições ligeiramente diferentes a cada vez, é possível que sua localização seja alinhada a um panorama diferente quando as imagens forem atualizadas.pano
: o ID do panorama específico da imagem a ser exibida. Se você especificar umpano
, também poderá especificar umviewpoint
. Oviewpoint
será usado apenas se o Google Maps não encontrar o ID do panorama. Se opano
for especificado, mas não for encontrado, e umviewpoint
for NÃO especificado, nenhuma imagem do panorama será exibida. Em vez disso, o Google Maps é aberto no modo padrão e exibe 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 sã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 para cima ou para baixo da câmera. A inclinação é especificada em graus de -90 a 90. Os valores positivos movem o ângulo da câmera para cima, e os valores negativos, 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 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 mais alto de zoom.
Exemplos do Street View
Os dois primeiros exemplos mostram um panorama da Torre Eiffel. No exemplo, um usa apenas 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 exibe uma imagem de panorama interna.
Exemplo 1: usa apenas um viewpoint
para especificar um local.
Exemplo 2: usa um ID pano
e um local viewpoint
.
O ID pano
tem prioridade sobre o viewpoint
.
Neste exemplo, o ID do panorama é encontrado, então viewpoint
é ignorado. Observe que a imagem do panorama exibida para o ID pano
é um pouco diferente e mais recente do que a imagem encontrada apenas com o viewpoint
.
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
Encontrar um ID de panorama
Para encontrar o ID de uma imagem de panorama específica, há vários métodos que podem ser usados.
- Para JavaScript, use a classe StreetViewPanorama.
- No Android, use a classe pública StreetViewPanoramaLocation.
- Para iOS, use a classe GMSPanorama.
- Também é possível fazer solicitações de metadados usando a API de imagens do Google Street View. As solicitações de metadados de imagem fornecem dados sobre panoramas do Street View, incluindo o ID do panorama.
Mais exemplos
Exemplos de rotas usando waypoints
Os exemplos de rotas a seguir iniciam o Google Maps e exibem rotas de carro de Paris, França, para Cherbourg, França, seguindo por estes waypoints:
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 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: pontos de referência definidos como cidade, país:
Exemplo 2: pontos de referência definidos como nomes de lugares específicos:
Exemplo 3: pontos de referência definidos como cidade e país e também fornecem 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 exibe waypoints na ordem em que estão listados no URL.
Exemplos de mapas
Exibe um mapa com um basemap
especificado (satélite) e um layer
(transporte público).
Exemplos do Street View
Exibe um panorama do Street View usando uma chave de imagem do FIFE como o ID pano
. O ID pano
é precedido por F:.